Eu Construí um Servidor MCP Personalizado Que Publica Meus Blogs Para Mim

Por Que Comecei Isso

Estive profundamente envolvido na preparação de engenharia de IA ultimamente — implementei alguns projetos de IA full-stack, ajustei um LLM de peso aberto e estive estudando DSA para colocações. Em algum lugar no meio de tudo isso, fiquei curioso sobre o MCP (Protocolo de Contexto do Modelo) e decidi realmente construir algo com isso em vez de apenas ler sobre.

A ideia era simples: e se Claude pudesse ler um rascunho de post de blog que estava no meu computador, limpá-lo e publicá-lo diretamente no Dev.to — sem eu tocar na interface do Dev.to?

Acontece que é exatamente para isso que o MCP serve.

O Que É MCP, Resumidamente

O MCP é um protocolo que permite que um modelo de IA como Claude chame ferramentas que você define — leia arquivos, acesse APIs, execute scripts — em vez de apenas gerar texto. Você escreve um pequeno servidor expondo "ferramentas" (funções Python simples com docstrings), conecta isso à configuração do Claude Desktop e, de repente, Claude pode agir, não apenas falar.

Eu configurei dois servidores para isso:

1. filesystem — um servidor MCP oficial que permite que Claude leia/escreva arquivos em uma pasta que eu permito
2. devto — um servidor personalizado que eu construí que expõe uma ferramenta publish_blog_to_devto, envolvendo a API do Dev.to

Configurando o Ambiente

Comecei com uv para gerenciamento de pacotes Python — muito mais rápido do que o pip/venv comum.

Primeiro obstáculo: o PowerShell não conseguiu encontrar uv logo após a instalação, porque minha sessão de terminal já estava aberta antes que o instalador atualizasse o PATH. Fechar e reabrir o terminal resolveu isso instantaneamente. Uma coisa pequena, mas fácil de entrar em pânico se você não souber por que isso está acontecendo.

O segundo obstáculo foi mais interessante. Eu criei um novo venv e tentei uv add "mcp[cli]", mas continuava falhando na resolução de dependências — porque meu pyproject.toml tinha requires-python = ">=3.9" deixado de quando o projeto foi inicialmente criado contra o Python 3.9 do sistema, mas o SDK do MCP real precisa de 3.10+. Eu corrigi isso fixando explicitamente:

uv python pin 3.12
uv venv --python 3.12

Então eu editei requires-python para >=3.10 em pyproject.toml, e a instalação foi concluída sem problemas.

A Armadilha do Nome do Pacote

Esse é o que realmente me pegou por um tempo. Após uma instalação supostamente bem-sucedida, importar fastmcp continuava lançando ModuleNotFoundError: No module named 'mcp.server.fastmcp' — mesmo que import mcp funcionasse bem e a pasta claramente tivesse um diretório server nele.

Acontece que uv pip show mcp revelou que o pacote instalado era a versão 2.0.0, com dependências como httpx2, mcp-types, pyjwt, e pywin32 — nenhuma das quais pertence ao verdadeiro SDK do MCP. Há um pacote não relacionado ocupando o nome mcp no PyPI, e ele foi puxado em vez do verdadeiro SDK modelcontextprotocol.

A correção foi fixar o intervalo de versão explicitamente:

uv remove mcp
uv add "mcp[cli]>=1.2.0,<2.0.0"

Isso puxou o SDK legítimo (1.29.0 na época), e from mcp.server.fastmcp import FastMCP finalmente funcionou.

Lição: se uv add somepackage "suceder" mas nada fizer sentido depois, verifique uv pip show — não assuma que o nome no PyPI é o projeto que você pensa que é.

Conectando ao Claude Desktop

O Claude Desktop lê sua lista de servidores MCP do claude_desktop_config.json, sob uma chave de nível superior mcpServers. Este arquivo tem outras preferências de aplicativo não relacionadas agora, então é fácil adicionar seu servidor acidentalmente como um irmão de mcpServers em vez de aninhado dentro dele — o que silenciosamente não faz nada. Aprendi isso da maneira mais difícil, olhando para Configurações → Desenvolvedor → Servidores MCP locais me perguntando por que apenas filesystem aparecia.

Forma correta:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:"\\Técnico\\mcp-código"]
    },
    "devto": {
      "command": "C:"\\Usuários\\vdine\\.local\\bin\\uv.exe",
      "args": ["--directory", "C:"\\Técnico\\custom-mcp\\devto-mcp-server", "run", "dev-server.py"]
    }
  }
}

Mais uma armadilha específica do Windows: o Claude Desktop nem sempre herda o PATH do seu shell, então "command": "uv" sozinho às vezes falha ao iniciar. Usar o caminho completo de where.exe uv resolveu isso de vez.

Após um fechamento completo e reabertura do Claude Desktop (não apenas fechando a janela — ele permanece na bandeja), ambos os servidores apareceram como em execução.

Testando Com o MCP Inspector

Antes de conectar qualquer coisa ao Claude Desktop, testei o servidor de forma independente usando:

uv run mcp dev src/mcp_server_demo/__init__.py

Isso inicia o MCP Inspector — uma interface web local onde você pode chamar suas ferramentas diretamente e ver os payloads de requisição/resposta brutos, sem precisar do Claude no meio. Genuinamente útil para pegar bugs cedo em vez de depurar através de uma interface de chat.

Publicando o Blog

Com ambos os servidores con