Como criar seu próprio servidor MCP em Python (em 10 minutos)

Crie, teste e conecte um servidor MCP mínimo com o SDK oficial de Python e o MCPServer, com dicas de design.

Escolha um SDK

Há SDKs oficiais para TypeScript, Python, C#, Java, Kotlin, Go e outras linguagens. Este guia usa o SDK oficial de Python 2.x, que exige Python 3.11 ou mais recente. Versões 1.x usavam FastMCP de mcp.server.fastmcp em vez de MCPServer.

1. Prepare o projeto

uv init demo && cd demo
uv add "mcp[cli]"

2. Escreva o servidor

Uma ferramenta é uma função comum com anotações de tipo e docstring; o SDK transforma isso no esquema e na descrição da ferramenta. mcp.run() inicia um servidor stdio.

# 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

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

3. Teste

Abra no MCP Inspector para chamar suas ferramentas por uma interface web:

uv run mcp dev server.py

4. Conecte a um cliente

Use um caminho absoluto. O Claude Desktop e o Cursor aceitam esta entrada; no Claude Code, execute claude mcp add demo -- uv run --with "mcp[cli]" mcp run /caminho/absoluto/server.py.

{
  "mcpServers": {
    "demo": {
      "command": "uv",
      "args": ["run", "--with", "mcp[cli]", "mcp", "run", "/absolute/path/to/server.py"]
    }
  }
}

Dicas de design

• Use nomes e descrições claros: o modelo escolhe as ferramentas lendo esses textos.
• Valide as entradas e devolva textos curtos e úteis.
• Não exponha ações destrutivas sem confirmação.
• Adicione o tópico mcp-server ao seu repositório no GitHub e o Socketlist vai listá-lo automaticamente.