/ Directorio / Playground / MCP Python SDK
← Todos los servidores ↗ GitHub
● Oficial modelcontextprotocol ⚡ Instantáneo

MCP Python SDK

por modelcontextprotocol · modelcontextprotocol/python-sdk

SDK oficial de Python para el Model Context Protocol — construye servidores y clientes en 30 líneas, incluye decoradores compatibles con FastMCP.

El SDK oficial de Python mantenido por Anthropic para MCP. Proporciona servidor (mcp.server.fastmcp.FastMCP), cliente (mcp.client.session.ClientSession) y primitivas de nivel más bajo. Usado como referencia canónica de cumplimiento de la especificación — cuando hay dudas, este es el punto de verdad. La API de FastMCP basada en decoradores se ha integrado desde jlowin/fastmcp.

▶ Ver demo 📦 Instalar 💡 Casos de uso

Por qué usarlo

Características clave

Demo en vivo

Cómo se ve en la práctica

mcp-python-sdk.replay ▶ listo
0/0

Instalar

Elige tu cliente

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mcp-python-sdk",
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json
{
  "context_servers": {
    "mcp-python-sdk": {
      "command": {
        "path": "uvx",
        "args": [
          "--with",
          "mcp",
          "python",
          "-m",
          "mcp.server.example"
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

claude mcp add mcp-python-sdk -- uvx --with mcp python -m mcp.server.example

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: MCP Python SDK

Construir tu primer servidor MCP en Python en menos de 10 minutos

👤 Desarrolladores Python nuevos en MCP ⏱ ~15 min beginner

Cuándo usarlo: Quieres exponer una función Python a Claude.

Requisitos previos
  • Python 3.10+ — uv o pyenv
Flujo
  1. Instalar y crear el scaffold
    Usa uv para instalar mcp. Crea server.py con una herramienta: get_weather(city) que llame a una API pública.✓ Copiado
    → Archivo de 10 líneas con decorador @tool
  2. Ejecutar mediante stdio
    Ejecuta mcp dev server.py. Abre el MCP Inspector y verifica el listado de herramientas.✓ Copiado
    → Herramienta callable desde el inspector
  3. Agregar a Claude Desktop
    Agrega a claude_desktop_config.json. Prueba desde Claude.✓ Copiado
    → Respuesta en vivo en el chat

Resultado: Servidor MCP en Python funcionando y registrado con Claude.

Errores comunes
  • Usar print() en el handler rompe stdio — Usa logging a stderr; nunca escribas en stdout

Escribir pruebas de integración para un servidor MCP usando el cliente del SDK

👤 Desarrolladores que publican MCPs a producción ⏱ ~30 min intermediate

Cuándo usarlo: Necesitas pruebas de CI que demuestren que tu MCP se comporta correctamente.

Flujo
  1. Lanzar el servidor
    Usa mcp.client.stdio para lanzar server.py y llamar a list_tools(). Asegura los nombres esperados.✓ Copiado
    → Prueba exitosa
  2. Llamar a cada herramienta
    Para cada herramienta, llama con una entrada representativa y asegura el esquema de salida.✓ Copiado
    → Todas las herramientas verificadas
  3. Integrar con pytest
    Convierte en fixtures de pytest para que CI las ejecute en cada PR.✓ Copiado
    → Arnés de prueba reutilizable

Resultado: Servidor MCP con confianza de que las herramientas no regresarán.

Transmitir en streaming la salida de herramientas de larga duración de vuelta a Claude mientras sucede

👤 Desarrolladores construyendo MCPs para builds, despliegues o simulaciones largas ⏱ ~45 min advanced

Cuándo usarlo: La herramienta tarda minutos y quieres progreso en el chat, no después de que termine.

Flujo
  1. Usar transporte HTTP streamable
    Cambia de stdio a HTTP streamable. Emite eventos de progreso desde la herramienta.✓ Copiado
    → Claude muestra salida parcial durante la ejecución
  2. Agregar cancelación
    Respeta las solicitudes de cancelación para que el usuario pueda abortar si la herramienta tarda demasiado.✓ Copiado
    → La cancelación funciona a mitad de ejecución

Resultado: Herramientas que se sienten en tiempo real incluso cuando son lentas.

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

mcp-python-sdk + mcp-go-mark3labs

Poliglota — rendimiento crítico en Go, ML/datos en Python

mcp-python-sdk + mcp-registry

Publicar tu MCP de Python en el registro oficial

Herramientas

Lo que expone este MCP

HerramientaEntradasCuándo llamarCoste
FastMCP name, version? Creación del servidor a nivel superior 0
@server.tool decorator on async function Cada función que quieras exponer 0
@server.resource decorator with uri pattern Exposición de datos de solo lectura 0
@server.prompt decorator on prompt builder Plantillas de prompt reutilizables 0
ClientSession transport Probar o construir clientes MCP 0
stdio_server () Modo local 0

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API
N/A — biblioteca
Tokens por llamada
N/A
Monetario
Gratuito (MIT)
Consejo
Fija la versión del SDK en pyproject.toml; la especificación evoluciona

Seguridad

Permisos, secretos, alcance

Almacenamiento de credenciales: Lo que tus herramientas necesiten
Salida de datos: Controlado por tus handlers

Resolución de problemas

Errores comunes y soluciones

Herramienta que no aparece

Asegúrate de que el decorador @tool esté en una función async y que la función esté registrada antes de que el servidor arranque

Verificar: Ejecuta `mcp dev server.py` y abre el inspector
Errores de validación de Pydantic

Los inputs de herramientas son validados por Pydantic; verifica que los type hints coincidan con lo que Claude está enviando

El servidor se cuelga al recibir EOF en stdin

Asegúrate de que tus handlers async no tengan deadlocks — usa anyio para compatibilidad

Alternativas

MCP Python SDK vs otros

AlternativaCuándo usarlaContrapartida
FastMCP (PrefectHQ)Quieres el fork de terceros original con utilidades adicionalesAhora en gran parte fusionado de vuelta; wrapper delgado
mcp-go (mark3labs)Go es tu idiomaEcosistema diferente

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills