/ Diretório / Playground / MCP Python SDK
← Todos os servidores ↗ GitHub
● Oficial modelcontextprotocol ⚡ Instantâneo

MCP Python SDK

por modelcontextprotocol · modelcontextprotocol/python-sdk

SDK Python oficial para o Model Context Protocol — crie servidores e clientes em 30 linhas, com decoradores compatíveis com FastMCP.

O SDK Python oficial mantido pela Anthropic para MCP. Fornece servidor (mcp.server.fastmcp.FastMCP), cliente (mcp.client.session.ClientSession) e primitivas de baixo nível. Usado como referência canônica de conformidade com a especificação — em caso de dúvida, esta é a fonte da verdade. A API de decoradores FastMCP foi mesclada a partir do jlowin/fastmcp.

▶ Ver demo 📦 Instalar 💡 Casos de uso

Por que usar

Principais recursos

Demo ao vivo

Como fica na prática

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

Instalar

Escolha seu 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
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

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

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

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

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

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

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

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

O Continue usa um array de objetos de servidor em vez de um map.

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

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

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

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: MCP Python SDK

Criar seu primeiro servidor MCP em Python em menos de 10 minutos

👤 Devs Python novos no MCP ⏱ ~15 min beginner

Quando usar: Você quer expor uma função Python ao Claude.

Pré-requisitos
  • Python 3.10+ — uv ou pyenv
Fluxo
  1. Instalar e criar scaffold
    Use uv to install mcp. Create server.py with one tool: get_weather(city) that calls a public API.✓ Copiado
    → Arquivo de 10 linhas com decorador @tool
  2. Executar via stdio
    Run mcp dev server.py. Open the MCP Inspector and verify the tool listing.✓ Copiado
    → Ferramenta chamável pelo inspector
  3. Adicionar ao Claude Desktop
    Add to claude_desktop_config.json. Test from Claude.✓ Copiado
    → Resposta ao vivo no chat

Resultado: Servidor MCP Python funcionando registrado no Claude.

Armadilhas
  • Usar print() no handler quebra o stdio — Use logging para stderr; nunca escreva no stdout

Escrever testes de integração para um servidor MCP usando o cliente do SDK

👤 Devs publicando MCPs em produção ⏱ ~30 min intermediate

Quando usar: Você precisa de testes de CI que provem que seu MCP se comporta corretamente.

Fluxo
  1. Inicializar o servidor
    Use mcp.client.stdio to spawn server.py and call list_tools(). Assert expected names.✓ Copiado
    → Teste passa
  2. Chamar cada ferramenta
    For each tool, call with a representative input and assert the output schema.✓ Copiado
    → Todas as ferramentas verificadas
  3. Integrar ao pytest
    Convert into pytest fixtures so CI runs them on every PR.✓ Copiado
    → Harness de testes reutilizável

Resultado: Servidor MCP com confiança de que as ferramentas não vão regredir.

Transmitir saída de ferramenta de longa duração de volta ao Claude conforme acontece

👤 Devs criando MCPs para builds, deploys ou simulações longas ⏱ ~45 min advanced

Quando usar: A ferramenta demora minutos e você quer progresso no chat, não depois que terminar.

Fluxo
  1. Usar transporte streamable HTTP
    Switch from stdio to streamable HTTP. Yield progress events from the tool.✓ Copiado
    → O Claude mostra saída parcial durante a execução
  2. Adicionar cancelamento
    Honor cancel requests so user can abort if the tool takes too long.✓ Copiado
    → Cancelamento funciona no meio da execução

Resultado: Ferramentas que parecem em tempo real mesmo quando são lentas.

Combinações

Combine com outros MCPs para 10× de alavancagem

mcp-python-sdk + mcp-go-mark3labs

Poliglota — performance crítica em Go, ML/dados em Python

Use mcp-python-sdk for the model-serving MCP, mcp-go for the high-throughput one.✓ Copiado
mcp-python-sdk + mcp-registry

Publicar seu MCP Python no registro oficial

Submit metadata to modelcontextprotocol/registry once your server passes its tests.✓ Copiado

Ferramentas

O que este MCP expõe

FerramentaEntradasQuando chamarCusto
FastMCP name, version? Criação do servidor de alto nível 0
@server.tool decorator on async function Cada função que você quer expor 0
@server.resource decorator with uri pattern Exposição de dados somente leitura 0
@server.prompt decorator on prompt builder Templates de prompt reutilizáveis 0
ClientSession transport Testes ou criação de clientes MCP 0
stdio_server () Modo local 0

Custo e limites

O que custa rodar

Cota de API
N/A — biblioteca
Tokens por chamada
N/A
Monetário
Gratuito (MIT)
Dica
Fixe a versão do SDK no pyproject.toml; a especificação evolui

Segurança

Permissões, segredos, alcance

Armazenamento de credenciais: O que suas ferramentas precisarem
Saída de dados: Controlado pelos seus handlers

Solução de problemas

Erros comuns e correções

Ferramenta não aparece

Certifique-se de que o decorador @tool está em uma função async e que a função foi registrada antes do servidor iniciar

Verificar: Execute `mcp dev server.py` e abra o inspector
Erros de validação do Pydantic

As entradas de ferramentas são validadas pelo Pydantic; verifique se os type hints correspondem ao que o Claude está enviando

Servidor trava no stdin EOF

Certifique-se de que seus handlers async não criam deadlock — use anyio para compatibilidade

Alternativas

MCP Python SDK vs. outros

AlternativaQuando usarTroca
FastMCP (PrefectHQ)Você quer o fork de terceiros original com utilitários extrasAgora em grande parte mesclado de volta; wrapper fino
mcp-go (mark3labs)Go é sua linguagemEcossistema diferente

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills