MCP 서버 개발 및 디버깅 방법(Python)

MCP(Model Context Protocol)은 Python 기반의 서버를 빠르고 유연하게 구현하고, 다양한 클라이언트(GUI/CLI)와 연동할 수 있는 플랫폼입니다. 이 글에서는 uv를 이용한 프로젝트 생성부터 개발 모드, Inspector 디버깅, 그리고 프로덕션 실행까지 MCP 서버 개발 전 과정을 정리합니다.

---

사전 준비

1. Python 3.8 이상 설치 및 가상환경 생성

   python -m venv .venv
   source .venv/bin/activate  # Windows에서는 .venv\Scripts\activate

2. uv 설치

   pip install uv

3. MCP CLI와 Inspector 플러그인 설치

   uv add "mcp[cli]"

---

1. 프로젝트 생성

uv init mcp-server-demo
cd mcp-server-demo
uv add "mcp[cli]"

uv init 명령어로 pyproject.toml 기반의 워크스페이스를 생성하고, uv add로 MCP 서버 실행 도구를 설치합니다.

---

2. MCP 서버 코드 작성 (main.py)

프로젝트 루트에 main.py를 생성하고, 간단한 Echo 서버를 구현합니다.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Echo Server")

@mcp.tool()
def echo(message: str) -> str:
    return f"Echo: {message}"

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

@mcp.tool() 데코레이터를 사용하여 외부에서 호출 가능한 함수를 등록합니다.

---

3. 개발 모드 및 Inspector 디버깅

3.1 MCP 서버 개발 모드 실행

mcp dev main.py

Inspector를 위한 WebSocket 및 디버깅 정보가 활성화된 상태로 서버가 실행됩니다.

3.2 MCP Inspector 실행

브라우저에서 http://127.0.0.1:6274 주소로 이동하면 MCP Inspector UI가 로드됩니다.

3.3 MCP Inspector를 통한 디버깅 단계

1. 서버 연결

   좌측 하단의 Connect 버튼을 클릭하여 서버에 연결합니다.

2. 도구(Tool) 테스트

   상단 메뉴에서 Tools 탭을 선택하고, List Tools 버튼을 클릭하여 등록된 도구 목록을 확인합니다. 테스트할 도구를 선택하고, 필요한 입력값을 입력한 후 Run Tool 버튼을 클릭하여 실행 결과를 확인합니다.

3. 리소스(Resource) 확인

   Resources 탭을 선택하여 서버에서 제공하는 리소스 목록을 확인합니다. 특정 리소스를 선택하여 내용을 조회하거나, 필요한 경우 구독 테스트를 수행할 수 있습니다.

4. 실시간 코드 수정 및 반영

   main.py 파일에서 코드를 수정한 후 저장하면, MCP Inspector가 자동으로 서버를 재시작하여 변경사항이 반영됩니다. Inspector UI에서 변경된 도구나 리소스를 즉시 테스트하여 결과를 확인할 수 있습니다.

---

4. 프로덕션 배포 및 실행

4.1 프로덕션 모드 실행

mcp run main.py

개발 모드와 달리 Inspector 없이 경량화된 서버 실행에 적합합니다.

4.2 Claude Desktop 통합

mcp install main.py

MCP 서버를 Claude Desktop 등 클라이언트에 설치하여 통합 사용 가능합니다.

4.3 환경 변수 로드

mcp install main.py -f .env

.env 파일을 통한 민감 정보(토큰, 키 등) 주입을 지원합니다.

---

5. mcp run vs mcp dev 비교

명령어	용도	특징
mcp dev	개발 및 디버깅	Inspector 자동 연결, 재시작 지원
mcp run	프로덕션 실행	경량화, Inspector 미사용

---

추가 팁: Claude Desktop에서 가상환경 사용

claude_desktop_config.json 파일에서 MCP 서버를 가상환경에서 실행하려면, uv 명령어에 --directory 옵션을 추가하여 가상환경의 루트 디렉토리를 명시해야 합니다. 이렇게 하면 uv가 해당 디렉토리의 .venv 가상환경을 인식하고 그 안에서 서버를 실행합니다.

수정 전 구성

"Timezone Server": {
  "command": "uv",
  "args": [
    "run",
    "--with",
    "mcp[cli]",
    "mcp",
    "run",
    "D:\\myproject\\flutterproject\\mcp-server-demo\\main.py"
  ]
}

이 구성은 uv가 기본 시스템 환경에서 실행되므로, 프로젝트의 가상환경을 사용하지 않습니다.

수정 후 구성

"Timezone Server": {
  "command": "uv",
  "args": [
    "--directory",
    "D:\\myproject\\flutterproject\\mcp-server-demo",
    "run",
    "--with",
    "mcp[cli]",
    "mcp",
    "run",
    "main.py"
  ]
}

이렇게 하면 uv는 D:\myproject\flutterproject\mcp-server-demo 디렉토리의 .venv 가상환경을 사용하여 main.py를 실행합니다.

추가 팁

• main.py의 경로는 --directory로 지정한 디렉토리를 기준으로 상대경로를 적습니다.