Python으로 나만의 MCP 서버 만드는 방법 (10분 완성)

공식 Python SDK와 MCPServer로 최소한의 MCP 서버를 만들고 테스트하고 연결하는 방법, 그리고 설계 팁.

SDK 선택

공식 SDK는 TypeScript, Python, C#, Java, Kotlin, Go 등 여러 언어로 제공됩니다. 이 가이드는 Python 3.11 이상이 필요한 공식 Python SDK 2.x를 사용합니다. 이전 1.x 버전에서는 MCPServer 대신 mcp.server.fastmcp의 FastMCP를 사용했습니다.

1. 프로젝트 준비

uv init demo && cd demo
uv add "mcp[cli]"

2. 서버 작성

도구는 타입 힌트와 docstring이 있는 일반 함수입니다. SDK가 이를 도구의 스키마와 설명으로 바꿔 줍니다. mcp.run()은 stdio 서버를 시작합니다.

# server.py
from mcp.server import MCPServer

mcp = MCPServer("demo")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

if __name__ == "__main__":
    mcp.run()

3. 테스트

MCP Inspector에서 열면 웹 화면에서 도구를 호출해 볼 수 있습니다.

uv run mcp dev server.py

4. 클라이언트에 연결

절대 경로를 사용하세요. Claude Desktop과 Cursor는 아래 항목을 사용하며, Claude Code에서는 claude mcp add demo -- uv run --with "mcp[cli]" mcp run /절대/경로/server.py를 실행합니다.

{
  "mcpServers": {
    "demo": {
      "command": "uv",
      "args": ["run", "--with", "mcp[cli]", "mcp", "run", "/absolute/path/to/server.py"]
    }
  }
}

설계 팁

• 도구 이름과 설명을 명확하게 쓰세요. 모델은 이를 읽고 도구를 고릅니다.
• 입력을 검증하고 짧고 유용한 텍스트를 돌려주세요.
• 파괴적인 작업은 확인 없이 노출하지 마세요.
• GitHub 저장소에 mcp-server 토픽을 추가하면 Socketlist에 자동으로 등록됩니다.