mcp-brasil: an MCP server that wraps 70 Brazilian public data sources

The gap mcp-brasil fills: Brazilian public data behind one MCP endpoint

Brazilian government data is spread across dozens of portals, each with its own query syntax, pagination convention and rate limit. The Câmara dos Deputados, the Senado Federal, the Portal da Transparência, the TCU and eleven state courts of accounts all publish differently. An agent asked to compare health spending in São Paulo and Minas Gerais has to know which of those endpoints answers that question and how to call it. mcp-brasil's answer is to register 533 tools across 70 features and 15 thematic areas, then let the client pick. The README states that 66 of the APIs need no key and that 4 use free keys obtainable through a one-minute registration. The intended user is someone running an MCP-capable assistant (the README names Claude, GPT and Copilot) who wants to ask questions in Portuguese or English and get structured answers without writing a client per agency. It is a convenience layer over public infrastructure, not a data warehouse.

How the server is put together: auto-registry, async httpx, DuckDB for the big sets

The README describes an auto-registry design: adding a feature means creating a folder, with no manual configuration step. That explains the tool count. Each feature contributes its own tools, and the totals (533 tools, 131 resources, 102 prompts) are aggregated from those folders. Transport is FastMCP, with httpx async and Pydantic v2 underneath and rate limiting with backoff. Two mechanisms matter more than the rest. The first is smart discovery: a BM25 search transform filters 533 tools down to the ones relevant to the current context, which is the only reason a tool list this large is workable inside a model's context window. The second is local caching for the large datasets. The README lists SIAPA at roughly 813k properties, TSE 2014-2024 (candidates, assets, voting, social networks, FEFC), ANP fuel prices, INEP school census and ENEM, ISP-RJ public security, and ANAC aircraft and scheduled flights. Those are queried through embedded DuckDB, and the README says the cache is opt-in via an environment variable. Two orchestration tools sit on top: planejar_consulta builds execution plans that combine multiple APIs (the README's example is a deputy's expenses plus votes plus propositions), and executar_lote dispatches queries in parallel in a single call.

Installing it: pip, uvx, and the config block each client expects

Installation is a single command: pip install mcp-brasil, or uv add mcp-brasil. For Claude Code the README gives claude mcp add mcp-brasil -- uvx --from mcp-brasil python -m mcp_brasil.server. For Claude Desktop you add an entry to claude_desktop_config.json with command uvx and args ["--from", "mcp-brasil", "python", "-m", "mcp_brasil.server"]. VS Code and Cursor use a .vscode/mcp.json file with a servers key instead of mcpServers. Google Antigravity reads ~/.gemini/config/mcp_config.json globally or .agents/mcp_config.json per workspace. The env block in those examples carries three optional keys: TRANSPARENCIA_API_KEY, DATAJUD_API_KEY and META_ACCESS_TOKEN. The README notes that without them the remaining 36 APIs still work, which means the keyed set is smaller than the unkeyed one and you can start with an empty env. For clients that speak HTTP rather than stdio, fastmcp run mcp_brasil.server:mcp --transport http --port 8000 serves the endpoint at http://localhost:8000/mcp. The README does not document the environment variable that enables the DuckDB cache by name, so if you need the TSE or SIAPA datasets, check the repository for the exact key before assuming it is on.

Where mcp-brasil stops: upstream fragility, keyed features, and data licensing

The most consequential limitation is not technical. The README states plainly that mcp-brasil is not an official service of the Brazilian government or of any institution whose data it exposes, that the MIT licence covers only the code, that each data source carries its own licence in SOURCES.md, and that use is subject to ACCEPTABLE_USE.md. It instructs readers to read both before commercial, journalistic or decision-making use. That is an unusual amount of caution for a README, and it should be read as a signal rather than boilerplate: wrapping a public API does not transfer rights to its contents. The second limitation is upstream dependency. Every one of the 533 tools is a thin client over someone else's endpoint. When a court of accounts changes a field name or a portal rotates a URL, the corresponding tool breaks, and the failure surfaces inside a model's tool call rather than in a test suite. Eleven separate TCE features (SP, RJ, RS, PE, CE, ES, RN, PI, SC, TO and others) means eleven independent surfaces that can degrade on their own schedule. Third, the four keyed features are gated: without a Portal da Transparência key, the 54 tools in that feature are unavailable, and that feature is the one most people reach for first. Fourth, the DuckDB path is opt-in, so a default install will not have the large datasets and the tools that depend on them will behave differently than the README's dataset list suggests. Finally, the README does not describe how stale the local cache can get or how it is refreshed, which matters for anything time-sensitive.

What you would otherwise write, and how the approaches differ

The realistic alternative is a hand-written client per agency: a small Python module that calls the Câmara's open data API for propositions and votes, another for the Senado, another for the Portal da Transparência contracts endpoint, and so on. That approach gives you exactly the fields you need, tests you control, and no dependency on someone else's tool naming. It also means writing pagination, retry and rate-limit handling for each source separately, and re-doing it when a portal changes. mcp-brasil trades that control for coverage: you get 70 sources without writing 70 clients, and the auto-registry design means the project can add a source without you changing anything. The cost is that you inherit the project's tool surface, its discovery layer and its release cadence. A second alternative is to skip MCP entirely and query the portals directly from your own agent code with a general HTTP tool. That keeps the context window small and avoids the 533-tool discovery problem, but you lose planejar_consulta and executar_lote, which are the parts that make cross-source questions (a deputy's expenses against their votes) a single call rather than a hand-written join.

Maintenance, versioning and what the MIT licence does and does not cover

The release history shows v0.12.1, v0.13.0 and v0.14.0 between mid-April and late April 2026, with the repository last pushed in August 2026. Frequent minor releases at 0.x are consistent with a project still adding sources and adjusting tool signatures, which is a real upgrade cost: tool names and argument shapes are the interface your prompts depend on, and a minor bump can change them. Pin the version in your uvx or pip invocation rather than tracking latest, and read the release notes before moving. The licence split is the part to get right. The code is MIT, which is permissive and imposes no conditions on your use of the server itself. The data is not covered by that licence. SOURCES.md is where each source's terms live, and ACCEPTABLE_USE.md governs use of the server. Neither document is summarised in the README, so the only honest statement is that you have to read them; this is not a legal opinion and the project does not offer one either. The practical implication is that a permissive code licence tells you nothing about whether you may republish what the tools return.

Editorial conclusion

Adopt mcp-brasil if you already run an MCP client and need Brazilian federal, state or electoral data inside a conversation, and you accept that each upstream API keeps its own terms. Do not adopt it if your use is commercial or journalistic and you have not read SOURCES.md and ACCEPTABLE_USE.md, because the MIT badge covers the code only. Before wiring it into anything that matters, verify three things: that TRANSPARENCIA_API_KEY, DATAJUD_API_KEY and META_ACCESS_TOKEN are the only keys you need for your features, that the specific tool you plan to call still points at a live endpoint, and that the DuckDB cache path you set does not collide with another process.

Official sources

1. Issues
2. License: MIT
3. Mcp-Brasil/mcp-brasil on GitHub
4. README
5. Releases