brasil-mcp-essentials

MCP server brasileiro — privacy-first, CNPJ alfanumérico-ready. 14 utilities offline para devs BR: validação de documentos, parse de boleto, PIX BR Code, calendário de feriados.

Sem rede, sem PII coletada, sem dependência de API externa. Tudo roda local — perfeito para agentes (Claude Desktop, Cursor, ChatGPT, etc.) que precisam tratar dados brasileiros com privacidade.

Por que esse MCP existe

• CNPJ alfanumérico ready. A Receita Federal vai começar a emitir CNPJs alfanuméricos em julho/2026 (NT COCAD/SUARA nº 49/2024). Este pacote valida os dois formatos — legacy 14 dígitos e novo alfanumérico — auto-detectando. Seu agente não quebra quando o RF flipar a chave.

• Privacy-first. Validação e parse rodam 100% offline. Nada de chamada a API externa, nada de telemetria embutida por padrão. Opt-in opcional pra ajudar o projeto com metadata anônima.

• MCP-nativo. Cada tool é uma MCP tool com schema, descrição e ergonomia que o LLM realmente consegue selecionar bem.

• CLI bonus. Tudo que serve como MCP tool serve também como subcomando shell, para devs que ainda não usam um MCP client.

Instalação

# Via uv (recomendado)
uv tool install brasil-mcp-essentials

# Via pipx
pipx install brasil-mcp-essentials

# Via pip
pip install brasil-mcp-essentials

Configurar Claude Desktop / Cursor / outros MCP clients

Adicione ao claude_desktop_config.json (Claude Desktop) ou equivalente:

{
  "mcpServers": {
    "brasil-essentials": {
      "command": "brasil-mcp-server"
    }
  }
}

Reinicie o cliente. As 14 tools aparecem automaticamente.

Quick start no terminal

# Validar CPF
$ brasil-mcp validate-cpf 52998224725
{
  "valid": true,
  "formatted": "529.982.247-25",
  "raw": "52998224725",
  "error": null
}

# Validar CNPJ (legacy ou alfanumérico — auto-detecta)
$ brasil-mcp validate-cnpj 11.222.333/0001-81
{
  "valid": true,
  "formatted": "11.222.333/0001-81",
  "raw": "11.222.333/0001-81",
  "error": null,
  "format": "legacy"
}

# Parse de boleto bancário
$ brasil-mcp parse-boleto "34191790010104351004791020150008291070026000"
# (...detecta tipo, banco, valor, vencimento)

# Gerar BR Code PIX estático
$ brasil-mcp generate-pix-brcode \
    --chave joao@example.com \
    --nome "Joao da Silva" \
    --cidade "Sao Paulo" \
    --valor 12345
{
  "brcode": "00020126...6304ABCD",
  ...
}

# Próximo dia útil (pula fins de semana + feriados)
$ brasil-mcp proximo-dia-util 2026-09-04
{ "date": "2026-09-08", "dias_pulados": 3 }

Liste todos os comandos: brasil-mcp --help.

Catálogo de 14 tools

Validators (7)

Boleto (1)

PIX (2)

Calendar (4)

Detalhes completos de cada tool em docs/tools.md.

Convenções globais

• Input: strings de documento aceitam com ou sem máscara (normalização interna). Datas em ISO 8601 (YYYY-MM-DD).

• Output: validadores retornam { valid, formatted, raw, error }. Valores monetários sempre em centavos (int) — nunca float.

• Erros: estruturados { code, message_pt, message_en, suggestion? }. Códigos: INVALID_FORMAT, INVALID_LENGTH, INVALID_CHECKSUM, EMPTY_INPUT, REPEATED_DIGITS, etc. Inputs inválidos viram valid: false — nunca exceções não-tratadas.

Privacidade & telemetria

Default: nenhuma telemetria. Para opt-in (metadata anônima — nome da tool, sucesso/falha, latência, versão; nunca os inputs/outputs):

export BRASIL_MCP_TELEMETRY=1

Um ID anônimo é gerado no primeiro run e armazenado em $XDG_DATA_HOME/brasil-mcp/installation_id. Para desabilitar de novo, basta unset da variável.

Detalhes completos em docs/tools.md#telemetria.

Roadmap

Este é o Brasil Essentials MCP (Fase 1). Próximos sprints:

• v0.2 — Lookups com API externa: CEP via ViaCEP, FEBRABAN online, cotações BCB.

• v0.3 — Transport SSE + REST API com OpenAPI.

• v0.4 — Pacote npm gêmeo (@brasil-mcp/essentials).

• v0.5 — Submissão a registries: Smithery, glama.ai, mcp.so, Anthropic Directory.

Fases futuras (produtos separados):

• Brasil Match MCP (Fase 2) — Match contra base Receita Federal sem expor dado pessoal. KYC, anti-fraude, onboarding B2B.

• Brasil Compliance MCP (Fase 3) — Due diligence + KYC pago: sanções (CEIS/CNEP), processos (CNJ), IP (INPI), ambiental (IBAMA), trabalho (MTE), PEP screening.

Licença

MIT — veja LICENSE.

Contribuindo

Issues e PRs bem-vindos em github.com/brasil-mcp/essentials.

brasil-mcp-essentials is a Brazilian-focused MCP server + CLI providing 14 offline utilities for developers working with Brazilian data: document validators (CPF, CNPJ, PIS, RENAVAM, CNH, Voter ID, Credit Card), boleto parser, PIX BR Code parser/generator with QR codes, and Brazilian calendar tools (holidays, business days).

Headline feature: validates both legacy 14-digit CNPJs AND the new alphanumeric CNPJs that Brazil's Receita Federal will start issuing in July 2026 (NT COCAD/SUARA 49/2024). Future-proof your agent today.

Privacy-first. Everything runs offline. No external API calls. No telemetry by default — opt-in only, anonymous metadata.

Install:

uv tool install brasil-mcp-essentials

MCP config (Claude Desktop):

{ "mcpServers": { "brasil-essentials": { "command": "brasil-mcp-server" } } }

CLI:

brasil-mcp validate-cpf 52998224725
brasil-mcp parse-boleto "<47-digit string>"
brasil-mcp generate-pix-brcode --chave you@example.com --nome "Your Name" --cidade "Sao Paulo"

See the tool catalog for full schema documentation.

License: MIT.