AI Frontier5 days ago

MCP 커스텀 서버 만들기 — TypeScript·Python 초보자 가이드

클로드 같은 AI 비서에게 내가 소중히 정리해 둔 메모장이나 자주 쓰는 컴퓨터 스크립트를 직접 연결할 수 있다면 얼마나 편리할까요? 최근 AI 생태계에서 가장 뜨거운 주제인 모델 컨텍스트 프로토콜(MCP)을 활용하면, 복잡한 지식이 없어도 나만을 위한 맞춤형 AI 비서를 뚝딱 만들어낼 수 있습니다. 내 컴퓨터의 로컬 데이터와 AI를 하나로 매끄럽게 이어주는 커스텀 서버 구축법, 지금 바로 쉽고 재미있게 시작해 볼까요?

왜 나만의 커스텀 서버가 필요할까?

이미 인터넷에 공개된 다양한 MCP 서버들을 가져다 쓰는 것도 훌륭한 출발점입니다. 실시간 검색을 도와주는 브레이브 검색(Brave Search) 서버나 내 컴퓨터 안의 폴더를 읽어주는 도구만 연결해도 클로드의 활용도는 몰라보게 높아집니다.

하지만 진짜 재미있는 변화는 '나만의 데이터'를 다루기 시작할 때 일어납니다. 내 손으로 꾹꾹 눌러 담은 로컬 일기장, 회사 안에서만 쓰는 비공개 데이터베이스, 혹은 내가 자주 돌리는 파이썬 자동화 스크립트를 클로드에 연결하는 순간입니다. 이때 비로소 세상에 단 하나뿐인 나만의 초개인화 비서가 탄생합니다.

서버를 만든다고 해서 어렵게 생각하실 필요는 전혀 없습니다. 이제는 복잡한 네트워크 백엔드 지식을 깊이 알지 못해도 괜찮습니다. 단 몇 줄의 코드만 있으면 내 로컬 환경과 클로드를 안전하게 이어주는 튼튼한 통로를 뚝딱 완성할 수 있습니다.

TypeScript로 구현하기: 더 간결해진 v2 SDK

가장 먼저 살펴볼 도구는 웹 생태계의 대표 주자인 TypeScript입니다.

최근 공개된 TypeScript SDK v2는 기존의 복잡했던 설정 과정을 대폭 덜어내고 아주 직관적으로 재탄생했습니다. 이제는 @modelcontextprotocol/server 패키지에서 제공하는 McpServer 객체와 serveStdio 헬퍼만 있으면 단 몇 줄로 커스텀 서버를 실행할 수 있습니다.

TypeScript SDK v2를 기준으로 작성한 가장 기본적인 날씨 정보 제공 서버 예제를 함께 볼까요?

// TypeScript SDK v2 기준
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

const server = new McpServer({
  name: "my-weather-server",
  version: "1.0.0"
});

// 도구 등록하기
server.registerTool(
  "get-weather",
  {
    description: "특정 지역의 날씨 정보를 가져옵니다.",
    inputSchema: z.object({
      location: z.string().describe("날씨를 조회할 도시 이름 (예: 서울, 부산)")
    })
  },
  async ({ location }) => {
    return {
      content: [{ type: "text", text: `${location}의 현재 날씨는 맑음입니다.` }]
    };
  }
);

// stdio 방식으로 서버 실행
serveStdio(() => server);

이 코드를 실행할 때 초보 개발자가 가장 자주 맞닥뜨리는 치명적인 복병이 있습니다. 바로 표준 출력 노이즈 현상입니다.

클로드 데스크톱과 같은 프로그램은 우리가 만든 MCP 서버와 표준 입출력이라는 가상의 연결선으로 소통합니다. 이 연결선은 오직 정해진 규격의 JSON-RPC 데이터만 오갈 수 있는 깨끗한 전용 전화선과 같습니다.

그런데 디버깅을 하려고 무심코 코드 중간에 console.log를 남기면 어떻게 될까요? 이 행동은 전용 전화선에 갑자기 엄청난 소음을 질러버리는 것과 같습니다. 클로드가 갑자기 끼어든 정체불명의 텍스트 때문에 통신 오류를 일으켜 결국 연결이 뚝 끊어지고 맙니다.

따라서 MCP 서버 안에서 동작 과정을 관찰하고 싶을 때는 무조건 console.error를 사용해야 합니다. 이 명령은 표준 에러라는 별도의 예비 통로로 메시지를 내보내기 때문에 전용 전화선에 아무런 잡음도 유발하지 않고 안전하게 로그를 모니터링할 수 있도록 도와줍니다.

Python으로 구현하기: 데코레이터 한 줄의 마법

파이썬을 주무기로 사용하신다면, 새로운 Python SDK v2의 FastMCP 인터페이스로 훨씬 더 쉽고 간단하게 커스텀 서버를 만들 수 있습니다. 복잡한 설정 코드 대신, 평소 작성하던 일반 함수 위에 데코레이터 한 줄만 얹어주면 모든 준비가 끝납니다.

파이썬의 표준 기능인 타입 힌트와 함수 설명글만 잘 적어두면, @mcp.tool() 데코레이터가 이를 자동으로 읽어서 클로드가 이해할 수 있는 JSON 스키마 형식으로 알아서 변환해 줍니다. 가장 단순한 예시 코드로 어떻게 구현하는지 살펴보겠습니다.

python

# Python SDK v2 (FastMCP) 기준 예시
from mcp.server.fastmcp import FastMCP

# FastMCP 서버 인스턴스 생성
mcp = FastMCP("My Custom Server")

@mcp.tool()
def calculate_shipping(weight: float, zone: str) -> str:
    """배송 요금을 계산하는 도구입니다."""
    # print()는 통신을 방해하므로 사용하지 않고, 로깅 라이브러리를 사용해 출력합니다.
    price = weight * (1.5 if zone == "US" else 2.5)
    return f"배송료: ${price:.2f}"

여기서 꼭 기억해야 할 중요한 비밀이 하나 있습니다. 코드 내에서 습관적으로 사용하는 print() 함수를 절대 사용하면 안 된다는 점입니다. AI와 서버가 데이터를 주고받는 전용 통로를 print() 출력이 오염시키면 통신 연결이 뚝 끊어져 버리기 때문입니다. 로그나 디버깅 메시지를 남겨야 할 때는 파이썬 표준 라이브러리의 로깅 시스템을 사용하여 표준 에러로 출력해야 안전합니다.

개발과 등록 과정도 역대급으로 편리해졌습니다. 터미널에서 mcp dev server.py 명령어를 실행하면 코드를 수정할 때마다 알아서 실시간 반영되며, 6274 포트에서 열리는 웹 대시보드(MCP Inspector UI)에서 연동 상태를 바로 테스트할 수 있습니다. 개발이 모두 끝나면 mcp install server.py 명령어를 입력해 복잡한 경로 탐색 없이 Claude Desktop 앱에 한 번에 내 서버를 등록할 수 있습니다.

Claude Desktop에 나만의 서버 연동하기

멋진 커스텀 서버 코드를 완성했다면, 이제 내 컴퓨터에서 돌아가는 Claude Desktop에 연결해 줄 차례입니다. 설정 과정은 생각보다 아주 간단해요. Claude Desktop의 환경 설정 파일인 claude_desktop_config.json에 우리 서버를 실행하는 방법만 적어두면 됩니다.

먼저 이 설정 파일을 찾아 열어야 합니다. 운영체제에 따라 아래 경로로 이동해 보세요.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

만약 해당 폴더에 파일이 없다면 새롭게 메모장을 열어 직접 파일을 만드셔도 괜찮습니다. 파일을 열었다면 아래처럼 우리가 앞서 작성한 서버를 등록해 줍니다. 이때 스크립트 파일의 경로는 반드시 절대 경로로 적어야 오류 없이 인식됩니다.

json

{
  "mcpServers": {
    "my-python-server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp",
        "python",
        "/Users/username/mcp-server/server.py"
      ]
    }
  }
}

위 설정은 Python 서버를 가장 빠르고 안전하게 실행하는 uv run 방식을 활용한 예시입니다. 복잡하게 가상 환경을 만들고 패키지를 미리 설치할 필요 없이, 실행할 때 알아서 필요한 패키지를 받아 구동해 주는 간결한 기법이죠. 만약 TypeScript 서버를 등록하고 싶다면 npx -y tsx /절대경로/server.ts 형태로 명령어를 구성하여 빌드 단계 없이 바로 연동할 수 있습니다.

설정을 마쳤다면 Claude Desktop 앱을 완전히 종료했다가 다시 실행해 보세요. 대화창 오른쪽 아래에 플러그인 모양의 콘센트 아이콘이 활성화되었다면 모든 준비가 끝난 것입니다.

에이전트 시대를 나만의 무기로 준비하기

이제 AI는 단순히 주어진 명령만 수행하는 비서를 넘어, 우리가 일하는 방식을 직접 가르칠 수 있는 똑똑한 파트너가 되었습니다. 평소 자주 쓰던 TypeScript나 Python 코드가 있다면 고민하지 말고 나만의 첫 MCP 서버를 직접 만들어 보세요. 내 업무 흐름에 딱 맞춘 도구가 하나씩 늘어날 때마다, 나만의 맞춤형 에이전트와 함께 일하는 짜릿한 재미를 느껴보실 수 있을 겁니다!