MCP Python SDK
MCP 서버·클라이언트를 만드는 공식 파이썬 SDK
uv add "mcp[cli]"Model Context Protocol 을 파이썬으로 구현하는 공식 SDK 입니다. stdio, Streamable HTTP, SSE 세 전송 방식을 모두 지원하며 서버와 클라이언트를 같은 패키지로 만듭니다. 2026-08 에 v2 로 대규모 재작성이 있었고 pip install mcp 가 이제 2.x 를 설치하므로, 마이그레이션 전이라면 상한을 걸어야 합니다.
판단
이럴 때 씁니다
- 파이썬으로 MCP 서버를 만들어 사내 데이터나 기능을 에이전트에 노출할 때
- MCP 클라이언트를 직접 구현해 여러 서버를 붙여야 할 때
- stdio 외에 Streamable HTTP 나 SSE 전송이 필요할 때
- 프로토콜 최신 개정을 빨리 따라가야 할 때
이럴 땐 쓰지 마세요
- 타입스크립트 생태계에 붙일 때는 공식 TypeScript SDK 가 맞습니다
- 서버를 직접 만들 필요 없이 이미 있는 MCP 서버만 쓸 때
- 프로토콜 세부를 감추고 더 얇은 API 만 원할 때는 FastMCP 같은 상위 래퍼가 편합니다
차별점
- 프로토콜을 정의하는 곳에서 직접 관리하는 공식 구현입니다.
- 서버와 클라이언트를 같은 패키지로 만들 수 있습니다.
- stdio·Streamable HTTP·SSE 표준 전송을 모두 지원합니다.
- 2026-07-28 개정을 포함해 이전 개정까지 함께 지원합니다.
워크플로
- 01uv add "mcp[cli]" 로 SDK 와 CLI 를 넣습니다.
- 02서버 파일에서 도구·리소스·프롬프트를 데코레이터로 선언합니다.
- 03mcp dev server.py 로 인스펙터를 띄워 도구 호출을 눈으로 확인합니다.
- 04mcp run server.py --transport streamable-http 로 전송 방식을 바꿔 봅니다.
- 05클라이언트 설정에 등록해 실제 에이전트에서 호출합니다.
주요 명령
| 명령 | 설명 |
|---|---|
uv add "mcp[cli]" | SDK 와 mcp 명령을 함께 설치합니다. |
uv run mcp dev server.py | 인스펙터를 붙여 개발 모드로 서버를 띄웁니다. |
uv run mcp run server.py --transport streamable-http | Streamable HTTP 전송으로 서버를 실행합니다. |
uv run --with "mcp[cli]" mcp | 프로젝트 없이 일회성으로 CLI 만 씁니다. |
함정
설치 전에 확인하세요
- pip install mcp 가 이제 2.x 를 설치합니다. v1 코드를 쓰고 있다면 mcp>=1.28,<2 처럼 상한을 걸어야 합니다.
- v2 는 아키텍처를 다시 짠 대규모 변경이라 v1 에서 올릴 때 마이그레이션 문서를 먼저 봐야 합니다.
- v1.x 는 v1.x 브랜치에서 치명적 버그와 보안 패치만 받습니다.
- cli 엑스트라를 빼면 mcp 명령이 설치되지 않습니다.
비교
FastMCP 가 서버를 빨리 만드는 데 초점을 둔 상위 프레임워크라면, 이쪽은 프로토콜 그 자체의 기준 구현입니다. 규격을 정확히 따라야 하거나 클라이언트까지 만들어야 하면 이쪽이 맞고, 도구 몇 개를 빠르게 노출하는 것이 목적이면 상위 래퍼가 손이 덜 갑니다.
최근 변경
2026-08-26 v2.0.1 을 기준으로 v2 계열이 안정 릴리스가 됐습니다. v1 의 오래된 구조 문제를 고치면서 2026-07-28 규격을 지원합니다. pip install mcp 가 2.x 를 설치하므로 마이그레이션 전이라면 버전 상한이 필요합니다.