Brasil Essentials

PyPI version Python versions License: MIT CI

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 [email protected] \
    --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.

uv tool install brasil-mcp-essentials

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

brasil-mcp validate-cpf 52998224725
brasil-mcp parse-boleto "<47-digit string>"
brasil-mcp generate-pix-brcode --chave [email protected] --nome "Your Name" --cidade "Sao Paulo"