[mcp] Python SDK 공식 README

원문: https://github.com/modelcontextprotocol/python-sdk/blob/main/README.md

목차

• 개요
• 설치
  • Python 프로젝트에 MCP 추가하기
  • 독립 실행형 MCP 개발 도구 실행
• 빠른 시작
• MCP란?
• 핵심 개념
  • 서버
  • 리소스
  • 도구
  • 프롬프트
  • 이미지
  • 컨텍스트
• 서버 실행하기
  • 개발 모드
  • Claude Desktop 연동
  • 직접 실행
  • 기존 ASGI 서버에 마운트
• 예제
  • Echo 서버
  • SQLite Explorer
• 고급 사용법
  • 저수준 서버
  • MCP 클라이언트 작성
  • MCP 원시 개념(Primitives)
  • 서버 기능(Capabilities)
• 문서
• 기여
• 라이선스

---

개요

Model Context Protocol(MCP)은 LLM(대형 언어 모델)에 컨텍스트를 표준화된 방식으로 제공할 수 있게 해주는 프로토콜입니다. 이 Python SDK는 MCP의 전체 명세를 구현하여 다음을 쉽게 할 수 있습니다:

• 어떤 MCP 서버에도 연결할 수 있는 MCP 클라이언트 구축
• 리소스, 프롬프트, 도구를 노출하는 MCP 서버 생성
• stdio, SSE, Streamable HTTP 등 표준 트랜스포트 사용
• 모든 MCP 프로토콜 메시지와 라이프사이클 이벤트 처리

설치

Python 프로젝트에 MCP 추가하기

uv를 사용하는 것을 권장합니다.

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

pip을 사용하는 경우:

pip install "mcp[cli]"

독립 실행형 MCP 개발 도구 실행

uv로 mcp 명령어 실행:

uv run mcp

빠른 시작

간단한 계산기 도구와 데이터를 노출하는 MCP 서버를 만들어봅시다:

# server.py
from mcp.server.fastmcp import FastMCP

# MCP 서버 생성
mcp = FastMCP("Demo")

# 덧셈 도구 추가
@mcp.tool()
def add(a: int, b: int) -> int:
    """두 수를 더합니다"""
    return a + b

# 동적 인사말 리소스 추가
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """개인화된 인사말 반환"""
    return f"Hello, {name}!"

Claude Desktop에 설치 후 바로 사용할 수 있습니다:

mcp install server.py

또는 MCP Inspector로 테스트할 수 있습니다:

mcp dev server.py

MCP란?

Model Context Protocol(MCP)은 LLM 애플리케이션에 데이터를 안전하고 표준화된 방식으로 노출하는 서버를 만들 수 있게 해줍니다. 웹 API와 비슷하지만 LLM 상호작용에 특화되어 있습니다. MCP 서버는 다음을 할 수 있습니다:

• 리소스: LLM 컨텍스트에 정보를 로드하는 GET 엔드포인트와 유사
• 도구: 코드 실행 등 부수효과를 내는 POST 엔드포인트와 유사
• 프롬프트: LLM 상호작용을 위한 재사용 가능한 템플릿
• 기타 다양한 기능

핵심 개념

서버

FastMCP 서버는 MCP 프로토콜의 핵심 인터페이스로, 연결 관리, 프로토콜 준수, 메시지 라우팅을 담당합니다. (라이프사이클 관리, 타입 세이프 컨텍스트 등 다양한 예시는 원문 참고)

리소스

리소스는 LLM에 데이터를 노출하는 방법입니다. REST API의 GET 엔드포인트와 유사하며, 데이터 제공에 집중하고 부수효과는 없어야 합니다:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My App")

@mcp.resource("config://app")
def get_config() -> str:
    return "App configuration here"

@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    return f"Profile data for user {user_id}"

도구

도구는 LLM이 서버를 통해 동작을 실행할 수 있게 해줍니다. 리소스와 달리 계산, 부수효과가 있습니다:

import httpx
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My App")

@mcp.tool()
def calculate_bmi(weight_kg: float, height_m: float) -> float:
    return weight_kg / (height_m**2)

@mcp.tool()
async def fetch_weather(city: str) -> str:
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.weather.com/{city}")
        return response.text

프롬프트

프롬프트는 LLM이 서버와 효과적으로 상호작용할 수 있도록 돕는 재사용 가능한 템플릿입니다:

from mcp.server.fastmcp import FastMCP
from mcp.server.fastmcp.prompts import base

mcp = FastMCP("My App")

@mcp.prompt()
def review_code(code: str) -> str:
    return f"Please review this code:\n\n{code}"

@mcp.prompt()
def debug_error(error: str) -> list[base.Message]:
    return [
        base.UserMessage("I'm seeing this error:"),
        base.UserMessage(error),
        base.AssistantMessage("I'll help debug that. What have you tried so far?"),
    ]

이미지

FastMCP는 이미지 데이터를 자동으로 처리하는 Image 클래스를 제공합니다. (예시는 원문 참고)

컨텍스트

Context 객체를 통해 도구/리소스에서 MCP의 다양한 기능에 접근할 수 있습니다. (예시는 원문 참고)

인증

OAuth2 인증 서버 연동 등 고급 인증 기능도 지원합니다. (예시는 원문 참고)

서버 실행하기

개발 모드

MCP Inspector로 서버를 빠르게 테스트/디버깅할 수 있습니다:

mcp dev server.py

Claude Desktop 연동

서버가 준비되면 Claude Desktop에 설치할 수 있습니다:

mcp install server.py

직접 실행

고급 배포 시나리오에서는 직접 실행도 가능합니다:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My App")

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

python server.py
# 또는
mcp run server.py

Streamable HTTP 트랜스포트

Streamable HTTP 트랜스포트는 SSE를 대체하는 최신 방식입니다. (상태 유지/무상태, FastAPI 연동 등 다양한 예시는 원문 참고)

기존 ASGI 서버에 마운트

Starlette, FastAPI 등 기존 ASGI 서버에 MCP 서버를 마운트할 수 있습니다. (예시는 원문 참고)

예제

Echo 서버

리소스, 도구, 프롬프트를 모두 보여주는 간단한 서버 예시입니다:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Echo")

@mcp.resource("echo://{message}")
def echo_resource(message: str) -> str:
    return f"Resource echo: {message}"

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

@mcp.prompt()
def echo_prompt(message: str) -> str:
    return f"Please process this message: {message}"

SQLite Explorer

데이터베이스 연동 예시입니다. (코드는 원문 참고)

고급 사용법

저수준 서버

더 세밀한 제어가 필요할 때 저수준 서버 구현을 직접 사용할 수 있습니다. (라이프사이클 관리, 타입 세이프 컨텍스트 등 다양한 예시는 원문 참고)

MCP 클라이언트 작성

고수준 클라이언트 인터페이스를 제공합니다. (코드는 원문 참고)

MCP 원시 개념(Primitives)

MCP 프로토콜은 서버가 구현할 수 있는 세 가지 핵심 원시 개념을 정의합니다:

Primitive	Control	Description	Example Use
Prompts	User-controlled	사용자 선택에 의해 호출되는 상호작용 템플릿	슬래시 명령, 메뉴 옵션 등
Resources	Application-controlled	클라이언트 앱이 관리하는 컨텍스트 데이터	파일 내용, API 응답 등
Tools	Model-controlled	LLM이 실행할 수 있는 함수	API 호출, 데이터 업데이트 등

서버 기능(Capabilities)

MCP 서버는 초기화 시 기능을 선언합니다:

Capability	Feature Flag	Description
prompts	listChanged	프롬프트 템플릿 관리
resources	subscribelistChanged	리소스 노출 및 업데이트
tools	listChanged	도구 검색 및 실행
logging	-	서버 로깅 설정
completion	-	인자 자동완성 제안

문서

• Model Context Protocol 공식 문서
• MCP 명세
• 공식 지원 서버

기여

모든 수준의 기여자를 환영합니다. 자세한 내용은 컨트리뷰팅 가이드를 참고하세요.

라이선스

이 프로젝트는 MIT 라이선스로 배포됩니다. 자세한 내용은 LICENSE 파일을 참고하세요.

---

번역: https://github.com/modelcontextprotocol/python-sdk

원문 출처 및 최신 정보는 위 링크를 참고하세요.