MCP Python SDK

이 페이지는 기계 번역본입니다

이 문서의 번역은 영어 페이지를 바탕으로 자동 생성되며, 기준이 되는 것은 이 페이지의 영어 원문입니다.

번역 문제를 발견했다면 번역이 만들어지는 방식과 문제를 신고하는 방법을 참고하세요.

현재 안정 릴리스 라인인 v2 문서

v2가 처음이거나 v1에서 넘어왔다면 v2에서 달라진 점에서 변경 사항을 5분 만에 둘러볼 수 있고, 마이그레이션 가이드가 모든 호환성 파괴 변경을 다룹니다. 아직 v1.x를 쓰고 있다면 문서는 v1.x 문서에 있습니다. 부족하거나 헷갈리는 부분이 있다면 알려주세요.

Model Context Protocol(MCP)은 애플리케이션이 표준화된 방식으로 LLM에 컨텍스트를 제공하게 해 주며, 컨텍스트를 제공하는 일과 LLM 상호작용 자체를 분리합니다.

이것이 그 공식 Python SDK입니다. 이를 사용하면 다음과 같은 일을 할 수 있습니다.

모든 MCP 호스트에 도구, 리소스, 프롬프트를 노출하는 MCP 서버를 구축합니다.
모든 MCP 서버에 연결하는 MCP 클라이언트를 구축합니다.
표준 트랜스포트를 모두 사용합니다. stdio, Streamable HTTP, SSE.

요구 사항

Python 3.10 이상.

설치

uvpip

uv add "mcp[cli]"

pip install "mcp[cli]"

[cli] 엑스트라를 설치하면 mcp 명령을 쓸 수 있으며, 개발할 때 필요합니다. 각 의존성이 어떤 역할을 하는지는 설치에서 확인하세요.

예제

만들기

server.py 파일을 만드세요.

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


@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

이것으로 완전한 MCP 서버가 완성됩니다.

도구 하나(add)와 템플릿 리소스 하나(greeting://{name})를 노출합니다.

실행하기

uv run mcp dev server.py

이 명령은 서버를 실행하고, 서버를 이리저리 시험해 볼 수 있는 대화형 UI인 MCP Inspector를 엽니다. 출력된 URL을 여세요.

Note

Inspector는 Node.js 앱이므로 mcp dev를 쓰려면 PATH에 npx가 있어야 합니다.

사용해 보기

Inspector에서 Tools로 이동해 a=1, b=2로 add를 호출하세요.

3이 돌아옵니다.

Inspector는 타입 힌트를 보고 그 폼(a용 필수 정수 필드와 b용 필수 정수 필드)을 만들었습니다. Claude를 비롯한 다른 모든 MCP 호스트도 마찬가지입니다.

이제 Resources로 이동해 greeting://World를 읽어 보세요.

Hello, World!

정리

작성하지 않은 것을 다시 살펴보세요.

JSON Schema가 없습니다. a: int, b: int 자체가 스키마입니다.
요청 파싱도, 직렬화도, 검증 코드도 없습니다.
프로토콜 처리 코드는 아예 없습니다.

타입 힌트와 docstring이 있는 Python 함수 두 개를 작성했을 뿐입니다. 나머지는 SDK가 처리합니다.

다음 단계

시작하기는 설치부터 동작하고 테스트까지 마친 서버까지 안내합니다.
MCP 서버를 사용하는 애플리케이션을 만든다면 클라이언트부터 시작하세요.
이미 FastAPI나 Starlette 앱이 있다면 기존 앱에 추가하기에서 그 안에 MCP 서버를 마운트하는 방법을 확인하세요.
정확한 오류 메시지를 찾고 있다면 문제 해결이 메시지 원문을 그대로 기준으로 정리되어 있습니다.
v2에서 무엇이 바뀌었는지 궁금하다면 v2에서 달라진 점에서 5분 만에 둘러볼 수 있습니다.
v1에서 마이그레이션한다면 마이그레이션 가이드부터 시작하세요.
정확한 시그니처를 찾고 있다면 API 레퍼런스가 소스에서 생성되어 있습니다.
LLM과 함께 읽고 있다면, 이 문서는 llms.txt 형식으로도 제공됩니다. llms.txt는 페이지 색인이고, llms-full.txt는 모든 페이지를 하나의 파일에 담고 있습니다.