Gerador de Servidor MCP Python

Crie um servidor Model Context Protocol (MCP) em Python com o SDK Python oficial do MCP v2. O SDK v2 suporta a revisão 2026-07-28 da especificação MCP. O mesmo servidor também atende clientes que usam revisões anteriores.

Fluxo de Trabalho

Copie esta lista de verificação e acompanhe seu progresso:

• Etapa 1: Crie o projeto.
• Etapa 2: Escreva o servidor.
• Etapa 3: Escreva os testes.
• Etapa 4: Execute os testes até que passem.
• Etapa 5: Configure o cliente.

Etapa 1: Crie o projeto

Execute estes comandos:

uv init --app --no-package project-name
cd project-name
uv add "mcp[cli]>=2,<3"
uv add --dev pytest

Em seguida, exclua main.py. O servidor vai em server.py.

• Sem --no-package, o uv cria um layout de pacote src/, e os testes não conseguem importar server.py.
• uv init cria o arquivo .gitignore. Não escreva um diferente.

Etapa 2: Escreva o servidor

Comece com este modelo:

from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

mcp = MCPServer("Demo", version="0.1.0")


@mcp.tool()
def divide(a: float, b: float) -> float:
    """Divide a by b."""
    if b == 0:
        raise ToolError("b must not be zero.")
    return a / b


if __name__ == "__main__":
    mcp.run()  # stdio is the default transport

Em seguida, altere o modelo para a solicitação do usuário:

1. Substitua divide pelas ferramentas que o usuário precisa.
2. Dê a cada ferramenta dicas de tipo completas e uma docstring. O SDK cria o esquema de entrada a partir das dicas de tipo. A docstring se torna a descrição da ferramenta.
3. Retorne um modelo Pydantic ou um TypedDict quando o cliente precisar de dados legíveis por máquina. O SDK cria o esquema de saída a partir do tipo de retorno.
4. Use async def para I/O. O SDK executa uma ferramenta síncrona em uma thread de trabalho.
5. Marque uma ferramenta somente leitura com @mcp.tool(annotations=ToolAnnotations(read_only_hint=True)) (de mcp.types). Use destructive_hint=True para uma ferramenta destrutiva.
6. Adicione recursos (@mcp.resource("users://{user_id}")) e prompts (@mcp.prompt()) apenas quando o usuário os solicitar.

Use stdio por padrão. Leia references/streamable-http.md apenas quando o usuário solicitar um servidor remoto ou um servidor HTTP.

Etapa 3: Escreva os testes

Coloque test_server.py ao lado de server.py. Escreva um teste para cada ferramenta e para cada ToolError:

import pytest

from mcp import Client

from server import mcp


@pytest.mark.anyio
async def test_divide():
    async with Client(mcp) as client:
        result = await client.call_tool("divide", {"a": 6, "b": 3})
        assert result.structured_content == {"result": 2.0}


@pytest.mark.anyio
async def test_divide_by_zero():
    async with Client(mcp) as client:
        result = await client.call_tool("divide", {"a": 1, "b": 0})
        assert result.is_error
        assert "must not be zero" in result.content[0].text

• O Client em memória não precisa de subprocesso nem de porta. Ele se conecta com a revisão 2026-07-28.
• O pacote mcp instala anyio, que fornece o marcador anyio. Não adicione pytest-asyncio.

Etapa 4: Execute os testes até que passem

1. Execute uv run pytest.
2. Se um teste falhar, leia o erro. Corrija o servidor ou o teste.
3. Execute uv run pytest novamente.
4. Continue apenas quando todos os testes passarem.

Etapa 5: Configure o cliente

Para o VS Code, escreva .vscode/mcp.json:

{
  "servers": {
    "demo": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/project", "run", "server.py"]
    }
  }
}

Para o Claude Desktop, execute uv run mcp install server.py.

Informe ao usuário estes comandos:

• uv run server.py inicia o servidor stdio. O servidor espera por um host no stdin e não imprime nada.
• uv run mcp dev server.py abre o Inspetor MCP. O Inspetor precisa do Node.js.

Armadilhas

O SDK v2 e a revisão 2026-07-28 mudaram muitos padrões do SDK v1. Não copie exemplos do SDK v1.

• O SDK v2 removeu FastMCP e mcp.server.fastmcp. Importe a classe do servidor com from mcp.server import MCPServer.
• Importe Context, Image, Audio, Resolve, Elicit, ElicitationResult, AcceptedElicitation, Message, UserMessage e AssistantMessage de mcp.server.mcpserver.

…