Senado Brasil MCP Server

🇧🇷 Leia em Português

A public, hosted MCP server that gives AI assistants live, structured access to Brazilian Senate open data — no installation, no account, no API key. Point your MCP client at the hosted endpoint and start asking about senators, bills, votes, expenses, and more. It runs on Cloudflare Workers over Streamable HTTP.

It exposes 69 tools, 4 prompts, and 5 resources across two domains:

• Legislative — senators; bills and their tramitation; votes; committees; plenary sessions, results and presidential vetoes; party-bloc voting orientation; speeches and stenographic transcripts; blocs and leadership; federal legislation; and citizen participation via the e-Cidadania portal.
• Administrative — CEAPS parliamentary-quota expenses; housing allowance; civil servants and payroll; overtime; interns; procurement contracts and biddings; outsourced staff; petty-cash funds; and budget execution.

Data comes from three official sources — the legislative open-data API, the administrative open-data API, and the e-Cidadania portal. All tool responses are in Portuguese (pt-BR). See CHANGELOG.md for release history.

See it in action

Point a client at the endpoint and ask in plain language — English or Portuguese:

• "How did São Paulo's senators vote in the most recent floor votes?" → senado_search_votacoes
• "Show the legislative progress of PEC 45/2019 (a constitutional amendment proposal)." → senado_buscar_materias + senado_obter_materia
• "How much was spent on the CEAPS parliamentary allowance in 2024, broken down by expense type?" → senado_ceaps

The answers come live from the Senate's official open-data APIs — exact figures with provenance, not numbers guessed from training data.

Use it (hosted — no setup)

This is a remote, hosted, open-access server. To use it, point any MCP client at the Streamable HTTP endpoint — no install, no account, no API key, no configuration:

https://senado.sidneybissoli.com/mcp

OpenAI / ChatGPT app surface

For OpenAI Apps SDK submission and review, the Worker also exposes a curated MCP surface:

https://senado.sidneybissoli.com/mcp/openai-app-v2

This endpoint intentionally keeps the full public MCP server intact at /mcp, but limits tool discovery to 27 high-signal, intent-oriented tools for ChatGPT app use. /mcp/openai-app remains available as a legacy alias, but new ChatGPT app configurations should use /mcp/openai-app-v2 so clients fetch the current tool schema. The tools still call the same handlers and return the same provenance envelope; only the advertised surface is narrower. Any ChatGPT app listing should present this as an independent open-data research app, not as an official Senate, OpenAI or ChatGPT connector.

For ChatGPT Apps, those 27 tools also advertise a shared MCP Apps UI template at ui://senado-br-mcp/openai-app-dashboard-v2.html. The self-contained widget renders the returned structuredContent as a compact dashboard with metrics, main records, and source/provenance, without adding another model-visible data tool.

Public legal URLs for app review:

• Privacy policy: https://senado.sidneybissoli.com/privacy
• Terms of use: https://senado.sidneybissoli.com/terms

ChatGPT (Deep Research)

ChatGPT deep research (and company knowledge, and research workflows over the Responses API) only uses an MCP server that exposes exactly search and fetch — this server does, on top of the senado_* tools, on the full /mcp surface (not on the curated app profile). Point the connector at the hosted endpoint, no key required:

https://senado.sidneybissoli.com/mcp

search ranks the query against the senators in office and the active committees of the Senate and the National Congress and returns { id, title, url } (sen:<código> / com:<código>); fetch returns the document as readable Markdown — the senator's biography and mandates, or the committee's summary and board — with the canonical public page (the senator's profile on www25.senado.leg.br or the committee page on legis.senado.leg.br), which is what ChatGPT cites. Both carry the same provenance block as every other tool, in structuredContent and _meta (the text channel is the contract's JSON). In ChatGPT's developer mode (Settings → Security and login → Developer mode) any tool is callable — the senado_* tools remain the ones to use for data.

Install (any client)

For clients that launch MCP servers as a command — and for one-command setup — use the mcp-remote bridge. No build, no config, no key:

npx -y mcp-remote https://senado.sidneybissoli.com/mcp

• One-click (LobeHub): open the server page and click Install.
• Native remote URL (Claude Desktop/Code and other Streamable-HTTP clients): see Connecting MCP Clients.

Everything below Architecture (Prerequisites, Setup, Deploy) is only for optionally self-hosting your own instance — it is not required to use this public server.

Run locally (npx · stdio)

Prefer not to route queries through a third-party host (e.g. a newsroom policy)? The same server also runs as a local stdio process that talks directly to the official government APIs — same 69 tools, same provenance envelope, no Cloudflare in the loop. This is the npm/stdio channel, published as senado-br-mcp.

Point a command-based client (Claude Desktop/Code, etc.) at the package — npm fetches and runs it, no clone or build:

{
  "mcpServers": {
    "senado-br": {
      "command": "npx",
      "args": ["-y", "senado-br-mcp"]
    }
  }
}

To run it directly or hack on it, use the source checkout instead:

git clone https://github.com/SidneyBissoli/senado-br-mcp-cloudflare
cd senado-br-mcp-cloudflare
npm install
npm run build
node dist/cli.js   # serves MCP over stdio (Ctrl+C to stop)

Parity with the hosted server: the legislative and administrative tools are identical (same upstream APIs, same throttle/cache/provenance) — locally the L1 Cloudflare cache is a no-op, but the L0 in-memory cache still works, so results are the same. The only difference is the e-Cidadania list/corpus tools: without D1 they fall back to a live scrape of the ~5 REST highlights, flagged via meta.fonte / possivelDesatualizacao; the detail tools (obter_*) are identical. Logs go to stderr — stdout carries only the JSON-RPC protocol stream.

Agent Skill (optional)

This repo bundles a Claude Agent Skill at .claude/skills/senado-br/ that teaches Claude when to reach for this server and how to use its 69 tools well — a themed tool map, common question→tool playbooks, the provenance contract, and gotchas (dates, the codigoMateria bridge, e-Cidadania's open-set listing, pagination). It points back to the server's own senado://catalogo / senado://guia resources rather than duplicating them.

Claude Code auto-discovers it when you work in this repo. To use it elsewhere, copy .claude/skills/senado-br/ into your ~/.claude/skills/, or zip the folder and upload it in claude.ai (Settings → Features). The skill assumes the senado-br MCP server is connected (hosted or via npx).

Architecture