MCP Brasil
Connect MCP-compatible AI clients to Brazilian government and public-institution data.
The evidence presents most capabilities as reads from public data sources, supplies API credentials through environment variables, keeps large local datasets opt-in, and adds an MCP_BRASIL_LGPD_ALLOW_PII gate for datasets involving PII. The deployment workflow uses narrowly scoped OIDC permissions and records the prior revision for failure rollback. The README clearly distinguishes the MIT code license from source-specific data licenses and repeatedly disclaims official affiliation, justifying full source-attribution credit. Deductions apply because no per-action user-confirmation mechanism is shown; batch queries, network calls, downloads, cache writes, and forced refreshes still have effects; secret storage, log redaction, and incident handling are undocumented; dependencies have broad lower bounds without supplied locking, vulnerability scanning, or update-policy evidence; and rollback evidence chiefly covers Azure deployment rather than every tool or cache operation.
The project documents asynchronous HTTP, timeout and retry controls, backoff, Python 3.10–3.13 support, dependencies, and development commands, which adequately supports ordinary dependency availability. The major deduction is internal inconsistency: the same README reports 533 versus 525 tools, 70 versus 69 features, and incompatible API-key counts including 66 plus 4, 36 remaining, and 62 keyless APIs; the architecture counts also do not clearly reconcile with the headline total. No concrete runtime error messages, degraded-mode responses, or actionable failure examples are supplied, so failure messaging receives only thin credit.
The README addresses developers, researchers, journalists, and high-stakes domains through a thematic catalog, natural-language scenarios, configurations for several MCP clients, HTTP operation, environment controls, and opt-in datasets. This thoroughly supports audience coverage and environment fit. Boundaries are reasonably stated through unofficial-status notices, license separation, risk warnings, optional credentials, and dataset gates, but the referenced AUP and detailed guides are absent from the supplied evidence. BM25 discovery, recommendation, and planning features support trigger precision, although tool schemas, ambiguity handling, and false-trigger analysis are not shown.
The package-by-feature architecture, directory tree, quick installation, client configurations, development commands, and contribution flow are clearly organized. The MIT text matches project metadata, earning full license credit. Known limitations are explicit about unstable or incomplete upstream APIs and possible model distortion, also earning full credit. Deductions apply because there is no substantive FAQ or troubleshooting example; headline count drift weakens naming and catalog stability; semantic release and a CHANGELOG path are configured but no changelog content is supplied; and maintenance is attributed only to a community and generic contributors, with no verified publisher, named maintainer, security contact, or service commitment.
Unifying numerous fragmented Brazilian public APIs, cross-source planning, batching, discovery, and optional DuckDB datasets behind MCP offers strong static evidence of marginal value. Natural-language examples, Pydantic-oriented architecture, and several client integrations support usable output, but no actual tool response samples, field-stability guarantees, or attached citation format are shown. Installation is simple and most APIs reportedly need no key, yet optional datasets range from roughly 100MB to 1.6GB, initial ingestion takes minutes, and API quotas, storage, or cloud operation may add costs; consequently cost-benefit handling is adequate rather than complete.
Many claims are traceable within the supplied material to source-by-feature tables, configuration tables, architectural descriptions, project metadata, and deployment workflows. Legal and provenance claims also point to SOURCES, NOTICE, and the AUP. Credit is deducted because those referenced files, implementation files, tests, and the mentioned lockfile are not supplied, leaving many coverage counts as README assertions, several of which conflict. The documentation clearly separates upstream data, server behavior, and possible downstream model inference or hallucination, while directing high-stakes users back to official sources, which fully supports fact/inference separation.
- README counts for tools, features, and keyless APIs conflict; verify the registry and implementation at the pinned revision before relying on coverage or capacity claims.
- Do not treat the project as an official government service; journalistic, judicial, medical, electoral, or other decision-making uses should verify results against current primary sources.
- Before enabling PII-bearing or large local datasets, review the unsupplied ACCEPTABLE_USE.md, SOURCES.md, and dataset guide, and establish LGPD, licensing, disk, and retention controls.
- The supplied evidence does not demonstrate dependency locking, vulnerability scanning, secret redaction in logs, or comprehensive error handling; audit these controls before deployment.
- Batch execution, forced refresh, and Azure dataset refresh can generate substantial requests and write or replace caches; apply quotas, monitoring, and recovery procedures.
What does this agent do, and when should you use it?
MCP Brasil is a self-hosted Python and FastMCP server spanning 15 subject areas, including economics, legislation, courts, elections, health, education, and public safety. The repository reports 70 features, 533 tools, 131 resources, and 102 prompts, with BM25 discovery used to surface contextually relevant tools. Most features call external APIs through asynchronous httpx clients, Pydantic v2 models, rate limiting, and retry backoff; selected large datasets are instead downloaded and queried through an embedded local DuckDB cache. Root-level meta-tools support feature listing, tool recommendations, multi-API query planning, parallel batch execution, and dataset discovery. It is a strong fit for teams that need broad Brazilian public-data access through MCP and can operate their own service, but it is unofficial and results intended for consequential use must be verified against the originating institution.
The mcp_brasil.server module auto-registers feature packages under data/, datasets/, and agentes/. REST features read Brazilian government and related public APIs with asynchronous HTTP clients, validate or structure responses with Pydantic, and expose the operations as MCP tools, resources, and prompts. recomendar_tools uses BM25 discovery to select relevant operations from the 533-tool catalog; planejar_consulta creates execution plans spanning multiple APIs; and executar_lote runs multiple queries in parallel within one call. Datasets enabled through MCP_BRASIL_DATASETS are downloaded from CSV or ZIP sources, ingested into a local DuckDB cache, and exposed through predefined query tools. Documented dataset examples include TSE candidates and votes, ANP fuel prices, INEP education records, and ANAC aviation data. The server runs over stdio for Claude Desktop, Claude Code, VS Code, and Cursor, or over HTTP at an /mcp endpoint.
- An economic analyst can retrieve Banco Central Selic, IPCA, exchange-rate, and GDP time series for comparative analysis.
- An investigative journalist can examine federal transparency records, contracts, suppliers, and state audit-court data, while verifying publishable findings with the official source.
- A legislative researcher can combine Câmara and Senado data on legislators, bills, votes, committees, and expenses.
- An election-research team can enable local TSE datasets to analyze candidates, declared assets, municipal voting, social links, and election-fund allocations from documented election years.
- A public-policy unit can cross-reference IBGE geography and population data with health, education, crime, or subnational fiscal indicators.
- An engineer adding another Brazilian API can follow the package-by-feature structure and validate the contribution with
make ci.
What are this agent's strengths and limitations?
- A single MCP server covers 70 documented features across 15 domains and exposes 533 tools, avoiding separate integrations for many Brazilian public APIs.
planejar_consultaandexecutar_loteprovide concrete support for cross-source planning and parallel batch queries.- BM25-based discovery narrows the large tool catalog to operations relevant to the current context.
- Optional DuckDB-backed datasets support repeated local analysis of large TSE, INEP, ANP, ANAC, and other published datasets.
- Documented stdio and HTTP modes, plus setup instructions for several MCP clients, reduce dependence on a single model vendor.
- The service depends on numerous third-party government and public APIs whose documentation, parameter coverage, and responses may be inconsistent.
- Optional local datasets range from roughly 100 MB to 1.6 GB and impose download time, disk usage, and initial ingestion costs.
- MIT applies only to repository code; every data source may have different licensing terms, and server use is governed by an Acceptable Use Policy.
- Health, judicial, and election data introduce legal and privacy obligations, with some personally identifiable datasets gated by
MCP_BRASIL_LGPD_ALLOW_PII. - The README contains inconsistent counts for keyless APIs and for the feature/tool catalog in different sections, so production adopters should validate the deployed inventory.
How do you install or deploy this agent?
Python is required. Install with pip:
pip install mcp-brasilOr with uv:
uv add mcp-brasilA documented direct launch through uvx is:
uvx --from mcp-brasil python -m mcp_brasil.serverOptional credentials include TRANSPARENCIA_API_KEY, DATAJUD_API_KEY, and META_ACCESS_TOKEN; some brapi.dev operations can also use a free token. The README gives conflicting counts for keyless APIs—66 in one section, 62 in another, and a separate reference to 36 remaining APIs—so adopters should verify credential requirements for the exact features they intend to use.
How do you use this agent?
For Claude Desktop, add an mcp-brasil entry under mcpServers in claude_desktop_config.json, set command to uvx, and use args equal to ["--from", "mcp-brasil", "python", "-m", "mcp_brasil.server"]. Add optional API keys under env.
For Claude Code, run:
claude mcp add mcp-brasil -- uvx --from mcp-brasil python -m mcp_brasil.serverFor VS Code or Cursor, create .vscode/mcp.json at the project root and configure the same uvx command and arguments.
For an HTTP client, run:
fastmcp run mcp_brasil.server:mcp --transport http --port 8000The endpoint is then available at http://localhost:8000/mcp. After connecting, issue a natural-language request such as comparing Selic and IPCA over the last 12 months. To use large local datasets, first set a value such as MCP_BRASIL_DATASETS=tse_candidatos,tse_bens,tse_votacao; the initial download and ingestion can take minutes.
How does this agent compare with similar options?
Compared with building a separate client for every Brazilian public-data API, MCP Brasil supplies one MCP interface with automatic feature registration, cross-source planning, and batch execution. Its REST passthrough features favor lightweight online access, while the optional DuckDB path trades local storage and initial ingestion time for repeatable queries over large historical datasets.
FAQ
Are API keys mandatory?
Is this an official Brazilian government service?
Does it download the large datasets by default?
MCP_BRASIL_DATASETS. The first activation downloads and ingests the selected files into DuckDB and may take several minutes.