Claude Desktop에서 파이썬으로 Local MCP 서버를 만들자.

MCP 서버를 자체 개발하기 위해 준비해야 할 것

• 파이썬 인터프리터
• uv 파이썬 패키지 관리 도구
• fastmcp 파이썬 모듈
• Claude Desktop

첫째, 파이썬 인터프리터 버전이 너무 오래된 것은 fastmcp 모듈이나 uv 사용에 문제가 될 수 있다. 이 예제를 위해 Python 3.8을 3.11로 업그레이드했다. 둘째, 파이썬 패키지 관리 도구인 uv만 있으면 프로젝트 관리와 패키지 관리(모듈 간 버전과 생성 관리)가 가능하다. 셋째, 파이썬 모듈 fastmcp는 MCP 서버와 클라이언트를 개발하기 위한 프레임워크로 파이썬에서 쉽게 MCP 서버를 구현할 수 있다. 넷째, Claude Desktop for Windows는 MCP 서버를 설치하고 AI 프롬프트를 이용하여 이용할 수 있다. 설치와 사용 방법은 다음 글을 참고한다.

"Claude Desktop에서 PlayWright MCP 서버를 적용해 보자." 읽어보기 >

uv 사이트 방문하기 >

Fastmcp 사이트 방문하기 >

파이썬으로 MCP 서버를 개발하자

2.1 uv와 프로젝트 설정

MCP 서버 개발을 위한 프로젝트와 파이썬 모듈 설치를 위해 uv가 필요하다. 아래 cmd 명령을 통해 uv를 설치한다.

powershell -ExecutionPolicy ByPass -c "irm <https://astral.sh/uv/install.ps1> | iex"

 

uv가 설치되면 MCP 서버 개발 디렉터리에서 다음 명령어로 mcp-server 프로젝트를 생성한다.

uv init mcp-server

 

예제 개발은 c:\do\systems\trip\mcp 디렉터리 아래 mcp-server 프로젝트를 만든다.

c:\do\systems\trip\mcp\mcp-server 디렉터리 아래 디렉터리와 파일들

이 파일 중 server_studio.py 파일은 MCP 서버 코딩 파일로 추가된 것이다.

프로젝트와 패키지 관리를 위해 중요한 파일은 pyproject.toml과 .venv이다.

pyproject.toml - 프로젝트 설정과 파이썬 모듈 패키지 버전 정보 .venv - 프로젝트를 위해 설치된 파이썬 모듈 위치

pyroject.toml은 아래와 같이 패키지 관리를 위한 버전 범위 등을 정의하고 있다. 패키지 범위는 "uv add" 명령어를 통해 설치될 때 업데이트된다.

[project]
name = "mcp-server"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "fastmcp>=3.0",
    "mcp[cli]>=2.0.0",
]

[project.scripts]
mcp-server = "mcp_server:main"

[build-system]
requires = ["uv_build>=0.12.5,<0.13.0"]
build-backend = "uv_build"

 

uv에 대한 자세한 소개는 다음 글을 참조한다.

"AI 프로젝트를 위한 - uv로 완성하는 AI 개발 환경 완전 가이드" 읽어보기 >

 

2.2 fastmcp 모듈 설치

MCP 서버 코딩에 필요한 fastmcp 모듈을 uv를 이용하여 설치한다. uv 명령은 해당 프로젝트 디렉터리에서 실행한다.

cd c:/do/systems/trip/mcp/mcp-server
uv add fastmcp

 

만일 특정 버전의 fastmcp 모듈을 설치하고 싶으면 다음 명령어를 사용한다. 예는 fastmcp 버전이 3.0을 설치하라는 명령이다.

uv pip install 'fastmcp>=3.0'

 

uv add 명령어로 패키지를 설치하면 프로젝트 디렉터리의 .venv 디렉터리 아래 패키지가 설치되는 것을 확인할 수 있다.

C:\Do\systems\trip\mcp\mcp-server\.venv\Lib\site-packages

 

2.3 MCP 서버 코딩

이제 프로젝트 디렉터리 아래 서버 로직을 구현한 server_studio.py 파일을 생성한다. 기존 더하기와 구별하기 위해 MCP tool 중 add()를 보면 결과에 10을 더하여 출력하게 되어있다.

from fastmcp import FastMCP

# Create an MCP server
mcp = FastMCP("Demo")
# Add an addition tool
@mcp.tool()
def StrangeAdd(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b + 10
# Add a dynamic greeting resource
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a personalized greeting"""
    return f"Hello, {name}!"
if __name__ == "__main__":
    mcp.run(transport="stdio")

 

Claude Desktop에서 MCP 서버를 사용하자

3.1 Claude Desktop에 MCP 서버 설치

Claude Desktop에서 MCP 서버 설치는 외부에서 제공하는 MCP 서버 설치와 동일하다.

 

"Claude Desktop에서 PlayWright MCP 서버를 적용해 보자." 읽어보기 >

 

claude_desktop_config.json 파일에 StudioServer라는 이름으로 MCP 서버가 설치되었다.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless"
      ]
    },
    "StudioServer": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Do/systems/trip/mcp/mcp-server",
        "run",
        "server_studio.py"
      ]
    }
  },

 

3.2 Claude에서 MCP 서버의 StrangeAddition 도구 사용하기

Claude Desktop에서 MCP 서버 실행을 확인한다.

개발한 MCP 서버가 동작하는지 확인

"MCP 서버를 이용해 덧셈하고 싶어"

MCP 서버 사용 전 확인

MCP 서버를 사용해 덧셈을 하지만 일반 지식과 차이까지 설명

 

개인적으로 Local MCP 서버가 필요해서 관련 내용을 준비하고 있다. 웹을 통한 서버 구현도 가능하며 Tool과 Resouce 이용 그리고 AI(Claude)를 위한 Tool에 대한 설명 등에 대한 조사도 준비 중이다.

2026 NDo

2026/8/15 처음 2026/8/15