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

What mcp-brasil actually connects

Brazilian public data is spread across dozens of separate portals, each with its own base URL, pagination style and response shape. The README frames mcp-brasil as an MCP server for 70 Brazilian public data sources, and the project counts 533 tools, 131 resources and 102 prompts across 15 thematic areas. The areas listed include economy, legislation, transparency, the judiciary, elections, environment, health, education, public security, subnational fiscal data and aviation.

The unit of work is the feature, not the API. Each feature maps to one upstream source and exposes a handful of tools: `bacen` covers Selic, IPCA, câmbio and PIB through the SGS series endpoint with 9 tools; `senado` exposes 26; `transparencia` exposes 54. If you only need one source, you are installing the whole registry to reach it.

The audience is developers wiring an agent to Brazilian government data, not analysts who want a dashboard. The README's own examples are natural-language questions about bills, Selic trends, federal contracts and campaign donors. Nothing in the repository suggests a hosted service, so the expectation is that you run the server yourself.

How the tool registry and transport work

The server is built on FastMCP, with httpx for async HTTP, Pydantic v2 for models and rate limiting with backoff. The README describes async everywhere and an auto-registry: adding a feature means creating a folder, with zero manual configuration. That is the interesting design decision, because 533 tools is far more than an agent can hold in context. The answer is a BM25 search transform that filters the tool list down to what is relevant to the current context, so discovery happens before invocation rather than by the model guessing a tool name.

Two tools go beyond single-source queries. `planejar_consulta` builds execution plans that combine multiple APIs, and the README gives the example of a deputy's expenses plus votes plus propositions. `executar_lote` fires queries in parallel in a single call. Those are the parts that make cross-source questions tractable, since a plan can be assembled once and dispatched as a batch instead of as a chain of round trips.

Large datasets take a different path. SIAPA (about 813k properties), TSE 2014-2024, ANP fuel prices, INEP school census and ENEM, ISP-RJ public security, and ANAC aircraft and scheduled flights are served through embedded DuckDB, with SQL available and the cache opt-in via an environment variable. So there are two mechanisms under one interface: live HTTP calls for most sources, local SQL for the ones whose size makes repeated API calls impractical. The README does not document what happens when a cached dataset is stale.

Installing mcp-brasil and making a first query

The package is on PyPI. Either of the two install forms below is enough, and the second is the one the repository's own tooling uses.

pip install mcp-brasil

uv add mcp-brasil

For Claude Code, the README gives a single command that registers the server. After it runs, the server appears in your MCP server list and its tools become callable in the session.

claude mcp add mcp-brasil -- uvx --from mcp-brasil python -m mcp_brasil.server

Clients that read a JSON config, such as Claude Desktop, take a block like the one below. The three environment variables are optional; the README states that without them the remaining APIs still work. The note in the README says 66 APIs require no key and 4 use free keys with a one-minute signup.

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": ["--from", "mcp-brasil", "python", "-m", "mcp_brasil.server"],
      "env": {
        "TRANSPARENCIA_API_KEY": "sua-chave-aqui",
        "DATAJUD_API_KEY": "sua-chave-aqui",
        "META_ACCESS_TOKEN": "seu-token-aqui"
      }
    }
  }
}

If you prefer HTTP instead of stdio, the README gives this command. The server then listens on port 8000 and the endpoint is http://localhost:8000/mcp.

fastmcp run mcp_brasil.server:mcp --transport http --port 8000

With the server connected, a first real use is a question rather than a tool call. The README's transparency example asks for the ten largest federal government contracts of 2024 and their suppliers. Expect the agent to search the tool list, pick the transparency tools, and return a structured answer; the exact fields depend on the upstream portal, not on this project.

Where mcp-brasil stops being the right tool

The licence boundary is the first limitation, and the README states it plainly: the MIT licence covers the code only, each data source has its own licence in SOURCES.md, and use of the server is subject to ACCEPTABLE_USE.md. For commercial, journalistic or decision-making use, the README tells you to read both. That means an agent answer produced through this server inherits the terms of whichever upstream source supplied the data, and those terms are not uniform across 70 sources.

Availability is the second. The server is a proxy in front of government portals that change, rate-limit or go down. The project applies rate limiting with backoff, which softens bursts but cannot create uptime that the upstream does not have. If your workflow needs a guaranteed SLA, this layer does not provide one.

The third is the shape of the output. The README does not document rollback, retry semantics per source, or how a partially failed `executar_lote` call reports which sub-queries succeeded. For exploratory agent questions that is fine. For anything that has to be reproducible, a direct call to the specific API, with your own caching and your own error handling, gives you a contract you control. The package metadata also marks the project as Development Status 4 - Beta, so the tool surface can move between minor versions.

mcp-brasil compared with calling the APIs directly

The alternative is not another MCP server. It is writing your own client against the handful of Brazilian APIs you actually need, using httpx or requests, and exposing only those functions to your agent.

The difference is in who owns the mapping. With mcp-brasil you get 533 tools, BM25-based discovery, batch execution and DuckDB-backed local copies of the large datasets, and you inherit its naming, its pagination handling and its rate limiting. With a direct client you write the mapping yourself for maybe three endpoints, which is a day of work, and in exchange you get full control over retries, caching, response shape and versioning. For a single source, the direct client usually wins.

The case for mcp-brasil is breadth and cross-referencing. Questions that span a deputy's expenses, votes and propositions, or that compare health spending per capita across two states using TCE-SP and IBGE, are exactly what `planejar_consulta` and `executar_lote` exist for. Writing that orchestration by hand across a dozen portals is the work this project has already done. Between the two, the deciding factor is how many sources your questions touch, not how sophisticated your agent is.

Maintenance, versions and licence boundaries

The repository is not archived and the last push was on 2026-08-19. Releases move at a moderate pace: v0.12.1 on 2026-04-14, then v0.13.0 and v0.14.0 both on 2026-04-24, and pyproject.toml still declares version 0.14.0. The changelog is generated, with cliff.toml in the repository root, so release notes are derived from commit history rather than hand-written.

Because the version is 0.x and the metadata classifies the project as Beta, expect tool names and parameters to change between minor releases. Pinning `mcp-brasil` to an exact version in your client config is the practical way to keep an agent working across an upgrade, and the CHANGELOG.md is where you check what moved.

On licensing: MIT applies to the code. SOURCES.md is the file that matters for the data, and ACCEPTABLE_USE.md governs use of the server. The README is explicit that mcp-brasil is an independent project and not an official service of the Brazilian government or of any institution whose data it reaches. Redistributing data pulled through the server, or using it in a product, is a question for the upstream terms, not for the MIT grant. This is not legal advice; read SOURCES.md for the sources you depend on.

Editorial conclusion

Adopt mcp-brasil if you are building agents that answer questions about Brazilian public data and you want the connector work already done: pip install mcp-brasil, or the uvx block in your client config, gets you 533 tools, and 66 of the 70 sources need no key. Do not adopt it if you need a stable, versioned data contract for regulated reporting, or if you cannot accept that the MIT licence covers the code only and each upstream source carries its own terms. Verify three things first: the four keyed features you actually plan to call, the SOURCES.md entry for every source you depend on, and whether the large datasets you need are among those that require MCP_BRASIL_DATASETS to be set before they are available.

Frequently asked questions

Official sources

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