brasil-data-mcp

MCP server that exposes Brazilian public data (CNPJ, CEP, banks, holidays) as tools for Claude Desktop, Claude Code, Cursor, Windsurf, and any client compatible with the Model Context Protocol.

Powered by BrasilAPI — no keys, no auth, official data.

🇧🇷 PT — What is it?

Connect your AI client to Brazilian public data without writing a single line of code. Ask in natural language:

• "What is the legal name for CNPJ 33.000.167/0001-01?"

• "Which city is this ZIP code 01310-100 in?"

• "Which bank has the code 341?"

• "What are the national holidays for 2026?"

Claude (or another MCP client) calls the tool, returns the structured JSON, and you read the answer in Portuguese directly in the conversation.

Available tools

Related MCP server: mcp-brasil

🇺🇸 EN — What is it?

Plug your AI client into Brazilian public data with zero code. Ask in natural language and the LLM picks the right tool, calls it, and answers you with structured data from official sources (Receita Federal, ViaCEP, BACEN).

Currently ships with consultar_cnpj. CEP, banks and holidays are landing next.

🚀 Installation

All instructions below use npx -y brasil-data-mcp, which downloads and runs the latest version without a global installation.

Claude Desktop

Edit the configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop. Done.

Claude Code

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

Cursor

Create or edit .cursor/mcp.json in the project root:

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

🛠️ Development

git clone https://github.com/alanpcf/brasil-data-mcp.git
cd brasil-data-mcp
npm install

npm run dev      # tsx watch — hot reload em desenvolvimento
npm run lint     # tsc --noEmit
npm run build    # tsup → dist/index.js
npm test         # vitest

To point your MCP client to the local build instead of the npm package:

{
  "mcpServers": {
    "brasil-data-local": {
      "command": "node",
      "args": ["/caminho/absoluto/para/brasil-data-mcp/dist/index.js"]
    }
  }
}

🗺️ Roadmap

• [x] Phase 1 — Skeleton + HTTP client + consultar_cnpj

• [x] Phase 2 — consultar_cep, consultar_banco, listar_bancos, consultar_feriados + Vitest tests

• [ ] Phase 3 — CI (GitHub Actions), CONTRIBUTING.md, coverage > 80%, npm publication

• [ ] Phase 4 — FIPE, DDD, ISBN, rates (SELIC/CDI/IPCA), CVM, MCP prompts for workflows

💡 Why this project exists

Most AI tools are trained and demonstrated with American data: ZIP code, EIN, FedEx tracking. When a Brazilian dev wants to ask an LLM "give me the registration for CNPJ X", they either resort to scraping, build an HTTP integration from scratch, or give up.

brasil-data-mcp is the shortest path: a single npx and your Claude (or Cursor, or Windsurf) already speaks "Brazilian public data Portuguese". Everything is open source, MIT, no keys, no hostile rate limits — because BrasilAPI has already done the heavy lifting of unifying and caching official data.

If you are a Brazilian dev and use LLMs daily, this server is for you.

🤝 Contributing

Issues and PRs are very welcome. To add a new tool, follow the pattern in src/tools/cnpj.ts (Zod schema + description + handler) and register it in src/index.ts.

Detailed guide in CONTRIBUTING.md (coming soon).

Built with ❤️ in Brazil. Powered by BrasilAPI.