🇧🇷 mcp-brasil

Servidor MCP que dá ao Claude, ao Cursor e a qualquer agente de IA acesso a dados públicos do Brasil: CEP, CNPJ, bancos, feriados, dias úteis, Tabela FIPE, DDD, Selic/CDI/IPCA, municípios do IBGE, domínios .br e ISBN.

Os dados vêm da BrasilAPI. O projeto não usa nenhuma dependência de runtime, implementa o protocolo diretamente e valida o CNPJ alfanumérico que a Receita Federal adotou em 2026.

Você: Quantos dias úteis tenho entre hoje e o Natal? E a empresa 00.000.000/0001-91 está ativa?

Claude: → calcular_dias_uteis(2026-11-11, 2026-12-25)
        → consultar_cnpj(00000000000191)
        São 31 dias úteis (descontei 20/11 e 25/12). O Banco do Brasil S.A. está com situação ATIVA desde...

Ferramentas

Todas as ferramentas são somente leitura e trazem as anotações readOnlyHint e openWorldHint. Por isso, os clientes podem aprová-las sem pedir confirmação a cada chamada.

Related MCP server: brasilapi-mcp

Instalação

Precisa de Node.js 20 ou mais recente.

Claude Code

claude mcp add brasil -- npx -y mcp-brasil

Claude Desktop

Adicione ao claude_desktop_config.json (em Settings → Developer → Edit Config):

{
  "mcpServers": {
    "brasil": {
      "command": "npx",
      "args": ["-y", "mcp-brasil"]
    }
  }
}

Cursor / Windsurf / VS Code

Use a mesma configuração acima em .cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json ou .vscode/mcp.json (no VS Code, a chave é servers).

Configuração

Exemplos de prompts

• "Valide esses CNPJs e me diga quais estão ativos: …"

• "Qual o vencimento de 15 dias úteis a partir de 18/12/2026?"

• "Quanto vale um Gol 2012 na FIPE?"

• "Qual banco é o 077 e qual o ISPB dele?"

• "O domínio padariadojoao.com.br está livre?"

• "Monte uma tabela com os feriados de 2027 que caem em dia de semana."

Arquitetura

src/
├── index.ts          # CLI: lê variáveis de ambiente e liga o servidor ao stdio
├── server.ts         # MCP sobre JSON-RPC 2.0: initialize, ping, tools/list, tools/call
├── lib/
│   ├── brasilapi.ts  # fetch com timeout, cache TTL e mensagens de erro em português
│   ├── schema.ts     # subconjunto de JSON Schema: descreve E valida os argumentos
│   └── validators.ts # CPF, CNPJ (numérico e alfanumérico) e CEP, offline
└── tools/            # uma ferramenta = { name, description, inputSchema, handler }

Algumas decisões de projeto:

• Zero dependências de runtime. O protocolo stdio do MCP é JSON-RPC com uma mensagem por linha. Implementar isso diretamente dá cerca de 150 linhas e deixa o npx instantâneo.

• Erros de ferramenta voltam com isError: true, e não como erro de protocolo. Assim o modelo lê a mensagem (por exemplo, "CNPJ inválido: confira os dígitos verificadores") e se corrige sozinho.

• Validação antes da rede. CEP, CNPJ, datas e domínios malformados são rejeitados sem chamar a API.

• Respostas enxutas. consultar_cnpj devolve só os campos úteis, para economizar contexto do modelo.

Desenvolvimento

npm install
npm test            # 53 testes com node:test, API mockada (roda offline)
npm run typecheck
npm run build
npm run inspector   # abre o MCP Inspector para testar as ferramentas na mão

Para adicionar uma ferramenta, crie o objeto Tool em src/tools/, registre em src/tools/index.ts e escreva o teste em test/tools.test.ts. O teste tools/list já checa nome, descrição e schema de todas.

Feito com IA

Este projeto foi escrito do início ao fim em pair programming com o Claude, da escolha da arquitetura aos testes. Ele faz parte de uma série de projetos de IA:

• mcp-brasil, este servidor MCP

• Plugin do Claude Code com skills e hooks que usam o mcp-brasil

• Sistema multiagente sobre os dados públicos brasileiros

• App 100% vibecodado

Licença

MIT. Os dados são da BrasilAPI e das fontes oficiais que ela agrega (Correios, Receita Federal, Banco Central, IBGE, FIPE, Registro.br). Confira os termos de cada fonte.