Como criar seu primeiro servidor MCP em Python: Guia Passo a Passo

Para criar seu primeiro servidor MCP em Python, você deve instalar a biblioteca oficial mcp da Anthropic, definir uma instância de servidor e utilizar decoradores como @server.list_tools() e @server.call_tool() para expor funcionalidades. Após escrever o script, configure o arquivo claude_desktop_config.json apontando para o seu executável Python. Isso permite que o Claude Desktop utilize suas funções locais de forma segura e padronizada através do protocolo aberto.

O ecossistema do Claude evoluiu significativamente com o lançamento do Model Context Protocol (MCP), um padrão aberto que resolve o problema da fragmentação entre modelos de IA e fontes de dados. Desenvolver um servidor MCP em Python é uma das formas mais eficientes de dar ‘superpoderes’ ao Claude, permitindo que ele interaja com APIs locais, bancos de dados e sistemas de arquivos sob seu controle total. Esta abordagem elimina a necessidade de criar integrações personalizadas para cada ferramenta, consolidando o acesso em um protocolo único e seguro.

O que é necessário para começar o desenvolvimento?

Antes de colocar a mão no código, você precisa garantir que seu ambiente de desenvolvimento esteja pronto. O SDK oficial do MCP para Python exige a versão 3.10 ou superior da linguagem. Recomendamos fortemente o uso do gerenciador de pacotes uv, desenvolvido pela Astral, que é atualmente a recomendação da Anthropic para lidar com dependências de forma rápida e isolada. Além do Python, você precisará do Claude Desktop instalado se quiser testar a integração visualmente, embora existam ferramentas de linha de comando para depuração técnica.

As fontes oficiais como modelcontextprotocol.io destacam que o MCP opera em uma arquitetura cliente-servidor simples. O servidor (que você vai criar) expõe capacidades, enquanto o cliente (Claude) decide quando e como usá-las com base no contexto da conversa. Certifique-se de ter permissões de escrita em seu sistema de arquivos, pois a configuração do cliente exigirá a edição de um arquivo JSON específico na pasta de dados do seu usuário.

Como estruturar o código do seu servidor Python?

O coração do seu servidor MCP será a classe Server da biblioteca mcp.server. Um script básico começa com a importação dos módulos necessários e a inicialização de um objeto servidor com um nome identificável. A comunicação padrão geralmente ocorre via stdio (entrada e saída padrão), o que torna o servidor leve e fácil de executar localmente. Abaixo, detalhamos a estrutura mínima:

Instalação: Execute pip install mcp ou use uv pip install mcp.
Importação: Importe Server e os tipos de transporte necessários.
Instanciação: Crie server = Server("nome-do-servidor").
Definição de Ferramentas: Use decoradores para registrar o que o servidor pode fazer.
Execução: Utilize o stdio_server_transport para iniciar o loop de escuta.

Segundo as documentações oficiais da Anthropic, a clareza nas descrições que você fornece no código é crucial. Como o Claude usa essas descrições para entender quando chamar a ferramenta, invista tempo explicando o que cada parâmetro faz dentro do próprio código Python.

Como registrar ferramentas e recursos no servidor?

No MCP, existem três conceitos principais: Resources (dados estáticos como arquivos), Prompts (modelos de instruções) e Tools (funções executáveis). Para a maioria dos desenvolvedores, as Tools são a parte mais interessante, pois permitem que o Claude execute ações. No Python, você registra uma ferramenta usando o decorador @server.list_tools(). Este método deve retornar uma lista de objetos Tool, definindo o nome, a descrição e o esquema de argumentos (JSON Schema).

Quando o Claude decide usar uma ferramenta, ele envia uma solicitação que é capturada pelo decorador @server.call_tool(). Dentro desta função, você escreve o código Python convencional — seja para consultar uma API de clima, ler um banco de dados SQL ou processar um arquivo local. A resposta deve ser retornada como uma lista de conteúdos (geralmente texto), que o Claude processará para responder ao usuário. É este fluxo que permite, por exemplo, que o Claude Code ou o Claude Desktop acessem informações em tempo real que não estavam no seu conjunto de treinamento original.

Como conectar e testar o servidor no Claude Desktop?

Uma vez que seu script Python (ex: meuserver.py) esteja pronto, você precisa avisar ao Claude que ele existe. Isso é feito editando o arquivo claude_desktop_config.json. No Windows, ele geralmente reside em %APPDATA%\Claude\claude_desktop_config.json; no macOS, em ~/Library/Application Support/Claude/claude_desktop_config.json.

Você deve adicionar uma entrada na seção mcpServers. A configuração deve especificar o comando para rodar seu servidor, que geralmente é python seguido pelo caminho completo do arquivo. Se estiver usando o uv, o comando seria uv run path/to/meuserver.py. Após salvar o arquivo, reinicie o Claude Desktop. Se tudo estiver correto, um ícone de martelo (ferramentas) aparecerá no chat, indicando que o servidor está ativo. Para depuração sem o Claude Desktop, a Anthropic oferece o mcp-inspector, uma ferramenta CLI que permite simular chamadas e verificar se o servidor está respondendo conforme o esperado, conforme detalhado em code.claude.com/docs.

Quais as melhores práticas de segurança e performance?

Segurança é um pilar do MCP. Como o servidor roda localmente, ele tem as permissões do seu usuário. Nunca exponha chaves de API sensíveis diretamente no código; use variáveis de ambiente. Além disso, valide rigorosamente as entradas recebidas no call_tool. Embora o Claude seja inteligente, ele pode ser induzido a enviar comandos maliciosos se o seu servidor não tiver travas de segurança (como sanitização de caminhos de arquivos).

Em termos de performance, mantenha as respostas das ferramentas concisas. Enviar megabytes de dados desestruturados pode estourar a janela de contexto do modelo ou tornar a interação lenta. Prefira usar Resources para grandes volumes de dados que o Claude pode ’ler’ sob demanda, em vez de passar tudo via ferramenta. O uso de bibliotecas assíncronas em Python (asyncio) também é recomendado para garantir que o servidor não bloqueie enquanto espera por respostas de rede ou processos pesados.

Perguntas frequentes

Preciso de uma assinatura paga do Claude para usar servidores MCP?

Não necessariamente. O uso de servidores MCP locais com o Claude Desktop está disponível para usuários do plano gratuito, desde que o aplicativo suporte a funcionalidade. No entanto, para usar o MCP via API (Claude Code) ou em ambientes de produção de larga escala, aplicam-se os custos normais de uso de tokens da API da Anthropic.

O MCP funciona apenas com Python?

Não. Embora o Python seja extremamente popular pela sua facilidade e bibliotecas de IA, a Anthropic também mantém um SDK oficial para TypeScript/JavaScript. Por ser um protocolo aberto baseado em JSON-RPC, qualquer linguagem capaz de lidar com entrada/saída padrão ou transporte HTTP pode tecnicamente implementar um servidor MCP.

Como o Claude sabe qual ferramenta usar no meu servidor?

O Claude analisa a descrição que você fornece ao registrar a ferramenta no código Python. Quando um usuário faz uma pergunta que parece exigir essa capacidade, o modelo gera uma chamada de ferramenta baseada no nome e nos parâmetros definidos. Por isso, descrições claras e detalhadas são fundamentais para o bom funcionamento.

Fontes e referências

#Python #Mcp #Claude #Tutorial #Ia #Desenvolvimento