io.github.matematicsolutions/br-eli-mcp

br-eli-mcp

MCP server for eight keyless, no-registration Brazilian open-data APIs:

1. Camara dos Deputados (dadosabertos.camara.leg.br) - the federal legislative process: bills (proposicoes) as they move through committees and floor votes.
2. Congresso Nacional Dados Abertos Legislativos (legis.senado.leg.br/dadosabertos) - the real LexML URN Lex resolver for enacted Normas Juridicas (laws, decrees, constitutional amendments): identification, Diario Oficial da Uniao publication provenance, amendment history, STF unconstitutionality notes.
3. normas.leg.br - the full-text companion to (2): real article-by-article text of enacted legislation, addressed by the same URN Lex.
4. DataJud CNJ (api-publica.datajud.cnj.jus.br) - court DOCKET metadata (not ruling text) across STJ/TST/TSE/TRFs/TJs/TRTs/TREs and military courts.
5. STJ Open Data Portal (dadosabertos.web.stj.jus.br) - real acordao (ruling) full text + ementa (headnote) from the Superior Tribunal de Justica, Brazil's second-highest court. Coverage starts May 2022.
6. CARF (acordaos.economia.gov.br) - real acordao (tax ruling) full text from Brazil's federal tax appeals board, by exact docket/decision number.
7. TST (jurisprudencia-backend2.tst.jus.br) - real ruling full text (inteiro teor) + ementa from the Tribunal Superior do Trabalho, Brazil's labor supreme court: free-text search and exact CNJ-process-number lookup (3,751,594 acordaos, 8,483,448 documents across all types - verified live 2026-07-07).
8. TCU (pesquisa.apps.tcu.gov.br) - real acordao full text (deliberation, rapporteur's report, vote) from the Tribunal de Contas da Uniao, the Federal Court of Accounts - public-procurement jurisprudence (525,620 acordaos - verified live 2026-07-07).

What this is (and isn't)

br_get_norma resolves a urn:lex:br:... against the Senado's own API gateway (public, no key or registration) and returns identification, publication provenance, and amendment history. br_get_norma_index + br_get_norma_texto resolve the same URN against normas.leg.br's structured Legislation tree for the real text of one article - not a summary. See DISCOVERY.md for how both endpoints were found: v0.1.0 tested the wrong host for identification and wrongly reported it as unconfirmed; v0.2.0 fixed that but still lacked full text; v0.3.0 found the full-text API on the same domain as the human-readable citation page.

This connector does not scrape Planalto (planalto.gov.br) HTML - no confirmed mechanical rule maps a URN Lex to a Planalto URL for every act type, and fabricating one would risk the citation-hallucination failure mode this fleet exists to prevent. Re-verified live 2026-07-07: legislacao.presidencia.gov.br (the REFLEGIS portal the manifest names) does not return a plain HTTP response to a keyless client at all - the connection is accepted but the request times out with zero bytes received, consistent with a bot-challenge/WAF in front of it, not a structured API. A minority of act types (mostly decrees) have no inline text in normas.leg.br either; for those, see DISCOVERY.md.

For case law, DataJud (docket metadata only, redistribution restricted by CNJ Resolution 446/2022), the STJ Open Data Portal (real acordao text, May 2022+), CARF (real tax-ruling text, exact lookup only), TST (real ruling text - free-text search and exact CNJ-process-number lookup, both confirmed live 2026-07-07 after a browser network trace of the real frontend revealed the request fields the earlier reverse-engineering missed) and TCU (real acordao/relatorio/voto text) are wired in below. TRF4/TRF5 were probed and rejected - their hosts never accept a connection from outside Brazil (geo_restricted) - and RFB's sijut2consulta is a scrape-class HTML app with no JSON backend. See DISCOVERY.md for the exact probes run and each confirmed request/response contract.

Tools

Bill type codes (sigla_tipo), for reference:

Every response carries lex_uri, human_readable_citation and source_url. For br_search_proposicoes/br_get_proposicao, lex_uri is Camara's own stable API URI (not a URN Lex - a bill isn't enacted law yet). For br_get_norma, lex_uri is the real urn:lex:br:... you queried with, e.g. "urn:lex:br:federal:lei:2002-01-10;10406" (Codigo Civil). For br_get_norma_texto, lex_uri is that URN plus the article suffix, e.g. "...;10406!art5".

Install

As a Claude plugin (Claude Code or the desktop app, needs uv):

/plugin marketplace add matematicsolutions/br-eli-mcp
/plugin install br-eli-mcp@br-eli-mcp

As a plain Python package:

pip install br-eli-mcp

Windows 11 with Smart App Control

Smart App Control blocks unsigned executables, which covers uvx.exe, pip.exe and the br-eli-mcp.exe launcher that pip writes at install time. The python.exe and py.exe from the python.org installer are signed by the Python Software Foundation, so running the module through the interpreter works:

python -m pip install br-eli-mcp
python -m br_eli_mcp

pip.exe is blocked for the same reason, so install with python -m pip, not pip install. If python is not on PATH, use the Windows launcher: py -3 -m br_eli_mcp.

{ "mcpServers": { "br-eli-mcp": { "command": "python", "args": ["-m", "br_eli_mcp"] } } }

Do not turn Smart App Control off to work around this - it cannot be re-enabled without reinstalling Windows.

Configuration

Data

The server runs on your machine. Each tool call sends your query to the official Brazilian public API it names above (Camara, Senado, normas.leg.br, DataJud CNJ, STJ, TST, TCU or CARF); nothing goes to MateMatic. Your query and the results also pass through whatever model you use, the same way as any other message.

Once, on first use, the standalone server also fetches a small configuration file (br-runtime.json.gz, updated source addresses) from this repository's GitHub Releases. That request carries no query content; GitHub's download counter for the file is the only usage signal we see. BR_ELI_RUNTIME_URL="" turns it off, and the Claude plugin ships with it off.

Two things are written locally, in your home directory:

• a response cache (~/.matematic/cache/br-eli), so a repeated lookup does not hit the source again. Court rulings are public records and can name the parties.
• an audit log (~/.matematic/audit/br-eli-mcp.jsonl), one line per tool call: the tool name, a SHA-256 hash of the input (not the input itself), result size, time and status.

Delete either folder at any time; BR_ELI_CACHE_DIR and BR_ELI_AUDIT_DIR move them.

License

Apache-2.0 (code). The Camara dos Deputados open-data API is open data requiring attribution - see SOURCES.md.