Mcp Senado

MCP Senado Federal — Brazilian Senate Open Data for AI Assistants

> Connect Claude, Cursor, Windsurf, and Continue.dev to the Brazilian Federal Senate (Senado Federal) legislative database with 56 tools covering senators, bills, voting records, committees, and plenary sessions.

[](https://opensource.org/licenses/MIT) [](https://github.com/cristianoaredes/mcp-senado/actions/workflows/ci.yml) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](https://www.npmjs.com/package/@aredes.me/mcp-senado)

[English](./README.en.md) | [Português](#) | [Contributing](./CONTRIBUTING.md)

---

What is this?

MCP Senado Federal is a Model Context Protocol (MCP) server that gives AI assistants direct access to the official Brazilian Federal Senate Open Data API. Once configured, you can ask Claude (or any MCP-compatible client) natural-language questions about Brazilian legislative data and get accurate, real-time answers sourced from the government's own API.

Who is it for?

• Data journalists investigating voting patterns or legislative proposals
• Academic researchers studying Brazilian parliamentary behavior
• Developers building civic tech apps or political dashboards
• Citizens and activists tracking specific bills or senators

---

Features

• 56 tools across 7 categories — senators, proposals, voting, committees, parties, plenary sessions, and reference data
• Multi-transport — stdio (native MCP) and HTTP/REST API modes
• Production-ready — circuit breaker, rate limiting, in-memory LRU cache, structured logging, and health checks
• Deployable anywhere — run locally via npx, Docker, or deploy globally on Cloudflare Workers (300+ edge locations)
• Secure by default — Zod input validation, optional bearer token auth, configurable CORS, PII masking, LGPD-compliant
• Type-safe — full TypeScript 5.7 with strict mode; 211 passing tests at 73% coverage
• Bilingual — documentation and tool descriptions in Portuguese and English

---

Available MCP Tools

Reference Data (10 tools)

| Tool | Description | |---|---| | ufs_listar | List all Brazilian states (UFs) | | legislaturas_listar | List Senate legislatures | | tipos_materia_listar | List legislative proposal types | | situacoes_materia_listar | List bill processing statuses | | tipos_comissao_listar | List committee types | | tipos_autor_listar | List author types | | tipos_sessao_listar | List session types | | tipos_votacao_listar | List voting types | | tipos_documento_listar | List document types | | assuntos_listar | List subject classifications |

Senators (13 tools)

| Tool | Description | |---|---| | senadores_listar | Search senators by name, party, state, or legislature | | senador_detalhes | Full details and biography for a specific senator | | senador_historico | Parliamentary history and previous terms | | senador_votacoes | Senator's voting record with filters | | senador_materias | Bills and proposals authored by the senator | | senador_discursos | Speeches delivered by the senator | | senador_licencas | Leaves of absence | | senador_comissoes | Committee memberships | | senador_liderancas | Leadership positions held | | senador_filiacao | Party affiliation history | | senador_profissoes | Declared professions | | senador_apartes | Interjections made on the floor | | senador_relatorias | Bills the senator has rapporteured |

Legislative Proposals (12 tools)

| Tool | Description | |---|---| | materias_pesquisar | Advanced search for bills and proposals | | materia_detalhes | Full details of a specific proposal | | materia_texto | Full text of a bill | | materia_votacoes | Voting sessions related to a proposal | | materia_tramitacao | Processing history and current status | | materia_autores | Authors and co-authors | | materia_relacionadas | Related bills | | materia_emendas | Amendments filed | | materia_pareceres | Committee opinions | | materia_notas_tecnicas | Technical notes | | materia_audiencias | Related public hearings | | materia_documentos | Attached documents |

Voting (5 tools)

| Tool | Description | |---|---| | votacoes_listar | List voting sessions with filters | | votacao_detalhes | Full details of a specific vote | | votacao_votos | Individual senator votes for a session | | votacao_orientacoes | Party/bloc voting orientations | | votacao_resumo | Statistical summary of a vote |

Committees (5 tools)

| Tool | Description | |---|---| | comissoes_listar | List all committees (permanent and temporary) | | comissao_detalhes | Committee details | | comissao_membros | Committee membership and composition | | comissao_reunioes | Meeting schedule and agendas | | comissao_materias | Bills under committee review |

Parties (5 tools)

| Tool | Description | |---|---| | partidos_listar | List all parties and parliamentary blocs | | partido_detalhes | Party details | | partido_membros | Senators affiliated with the party | | partido_liderancas | Party leadership | | blocos_listar | Parliamentary blocs and coalitions |

Plenary Sessions (6 tools)

| Tool | Description | |---|---| | sessoes_listar | Session calendar with filters | | sessao_detalhes | Details of a specific session | | sessao_votacoes | Votes held during a session | | sessao_discursos | Speeches delivered during a session | | sessao_ordem_dia | Session agenda (order of the day) | | sessao_expediente | Session dispatch (expediente) |

---

Installation

Requirements

• Node.js 18.x or higher
• npm 9.x or higher

Option 1 — npx (no install needed)

npx @aredes.me/mcp-senado

Option 2 — Global install

npm install -g @aredes.me/mcp-senado
mcp-senado

Option 3 — Clone and build

git clone https://github.com/cristianoaredes/mcp-senado.git
cd mcp-senado
npm install
npm run build

---

Usage — Connect to an AI Assistant

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "senado-federal": {
      "command": "npx",
      "args": ["-y", "@aredes.me/mcp-senado"],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Cursor / Windsurf

{
  "mcpServers": {
    "senado-federal": {
      "command": "npx",
      "args": ["-y", "@aredes.me/mcp-senado"]
    }
  }
}

Continue.dev

{
  "mcpServers": [
    {
      "name": "senado-federal",
      "command": "npx",
      "args": ["-y", "@aredes.me/mcp-senado"]
    }
  ]
}

Example prompts

Once connected, ask your AI assistant:

"List all senators from São Paulo"
"What is the voting record of Senator X on environmental bills?"
"Find all education bills introduced in 2024"
"What is the current status of PLS 123/2024?"
"Show the composition of the CCJ committee"
"How many senators does each party have?"

---

HTTP Server Mode

Run the server as a standalone REST API for web applications:

# Development
npm run dev:http

# Production
npm run build && npm run start:http

# Via npx
npx @aredes.me/mcp-senado-http

Base URL: http://localhost:3000

| Endpoint | Method | Description | |---|---|---| | /health | GET | Health check and server status | | /mcp | POST | MCP JSON-RPC endpoint | | /sse | GET | Server-Sent Events for MCP clients | | /api/tools | GET | List all available tools | | /api/tools/:name | GET | Get tool details | | /api/tools/:name | POST | Invoke a tool | | /api/categories | GET | List all categories | | /api/tools/category/:category | GET | Tools by category |

Example — invoke a tool via HTTP:

curl -X POST http://localhost:3000/api/tools/senadores_listar \
  -H "Content-Type: application/json" \
  -d '{"uf": "SP"}'

---

Docker

# Quick start
docker-compose up -d

# Manual build and run
docker build -t mcp-senado:latest .
docker run -d --name mcp-senado -p 3000:3000 mcp-senado:latest

# Check status
curl http://localhost:3000/health

---

Cloudflare Workers

Deploy to 300+ global edge locations:

npm install -g wrangler
wrangler login
npm run build
npm run deploy:workers:production

Local development with hot reload:

npm run dev:workers   # starts at http://localhost:8787

---

Configuration

Create a .env file or set environment variables:

# API
SENADO_API_BASE_URL=https://legis.senado.leg.br/dadosabertos/

# Cache
MCP_CACHE_ENABLED=true
MCP_CACHE_TTL=300

# Rate limiting
MCP_RATE_LIMIT_ENABLED=true
MCP_RATE_LIMIT_MAX_REQUESTS=30
MCP_RATE_LIMIT_WINDOW_MS=60000

# HTTP server
HTTP_PORT=3000
HTTP_AUTH_ENABLED=false
HTTP_AUTH_TOKEN=

# Logging
MCP_LOG_LEVEL=info

---

Architecture

AI Assistants (Claude, Cursor, Windsurf, Continue.dev)
    ↓ MCP Protocol (stdio / HTTP / SSE)
Adapters Layer (CLI, HTTP Server, Cloudflare Workers)
    ↓
Core Layer (MCP Server, Tool Registry, Zod Validation)
    ↓
Tools Layer (Senator, Proposal, Voting, Committee, Party, Session, Reference)
    ↓
Infrastructure Layer (HTTP Client, LRU Cache, Circuit Breaker, Rate Limiter)
    ↓ HTTPS
Senado Federal Open Data API (legis.senado.leg.br/dadosabertos)

---

Contributing

Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines, code of conduct, and how to submit pull requests.

---

License

MIT — see [LICENSE](./LICENSE) for details.

Data is sourced from the Brazilian Federal Senate Open Data API, a public service maintained by the Brazilian government.

---

Related Projects

• mcp-camara — MCP server for the Brazilian Chamber of Deputies
• mcp-dadosbr — MCP server for Brazilian public datasets

---

by Cristiano Arêdes

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cristianoaredes
• Source: cristianoaredes/mcp-senado
• License: MIT
• Homepage: https://github.com/cristianoaredes/mcp-senado

Install and usage instructions live in the source repository linked above.