Senado Br MCP

🚀 senado-br-mcp

MCP server for Brazilian Federal Senate open data (legislators, bills, votes, committees), enabling structured access to legislative information and facilitating interaction with AI.

🚀 Quick Start

The senado-br-mcp is an MCP (Model Context Protocol) server that provides structured access to the open data of the Brazilian Federal Senate. It democratizes access to legislative information through interactions with AI. There are two ways to use it: stdio/npm for local usage and HTTP remote for cloud access.

✨ Features

• 33 tools for accessing Senate data.
• Real-time data from the official API.
• e-Cidadania integration: Obtain citizen participation data via web scraping.
• Structured JSON responses.
• Error handling with actionable suggestions.
• TypeScript with full type safety.
• Two access modes: stdio (npm) and HTTP remote.

📦 Installation

Two Ways to Use

Both modes provide access to the same 33 tools.

Option 1: stdio/npm (Local)

Installation

• Using npx (Recommended):

npx senado-br-mcp

• Global Installation:

npm install -g senado-br-mcp
senado-br-mcp

• From Source:

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

Claude Desktop Configuration

Add to your claude_desktop_config.json:

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

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

Option 2: HTTP Remote (Cloud)

No installation required. Connect directly via URL.

Claude Desktop Configuration

In Claude Desktop settings, go to "Add Custom Connector" and enter:

• Name: senado-br-mcp
• URL: https://senado-br-mcp.up.railway.app/mcp

Endpoints

Rate Limiting

The HTTP server has a monthly request limit to stay within the free tier:

• Alerts are sent at 50%, 80%, and 100% usage.
• When the limit is reached, use the npm version instead.
• The limit resets on the 1st of each month.

💻 Usage Examples

List senators from São Paulo

Use senado_listar_senadores with uf: "SP"

Search for Constitutional Amendments in 2024

Use senado_buscar_materias with sigla: "PEC", ano: 2024

Get recent votes

Use senado_votacoes_recentes with dias: 7

Find a senator by name

Use senado_buscar_senador_por_nome with nome: "Randolfe"

Get CCJ committee members

Use senado_membros_comissao with sigla: "CCJ"

Get polarized public consultations

Use senado_ecidadania_consultas_polarizadas with minimoVotos: 5000

Get most supported citizen ideas

Use senado_ecidadania_ideias_populares with limite: 5

Find upcoming interactive events

Use senado_ecidadania_listar_eventos with status: "agendado"

📚 Documentation

Response Format

All tools return structured JSON responses:

Success Response

{
  "success": true,
  "data": { ... },
  "metadata": {
    "fonte": "Senado Federal - Dados Abertos",
    "dataConsulta": "2024-01-15T10:30:00Z",
    "endpoint": "/senador/lista/atual"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "SENADOR_NAO_ENCONTRADO",
    "message": "Senator with code 99999 was not found",
    "suggestion": "Use senado_buscar_senador_por_nome to find the correct code"
  }
}

🔧 Technical Details

Development

Prerequisites

• Node.js 18+
• npm

Setup

npm install

Build

# Build stdio version (npm package)
npm run build

# Build HTTP server version
npm run build:server

# Build both
npm run build:all

Development Mode

# stdio mode
npm run dev

# HTTP server mode
npm run dev:server

Type Check

npm run typecheck

Test with MCP Inspector

npm run inspect

Self-Hosting HTTP Server

You can host your own HTTP server instance.

Local

npm run build:server
npm run start:server
# Server runs on http://localhost:3000

Railway

1. Fork this repository.
2. Connect Railway to your GitHub.
3. Deploy (auto-detects configuration from railway.json).
4. Set environment variables:
   • MONTHLY_REQUEST_LIMIT (default: 10000)
   • ALERT_WEBHOOK_URL (optional, for notifications)

Environment Variables

Data Sources

Official API

• API: Senado Federal - Dados Abertos
• Documentation: https://legis.senado.leg.br/dadosabertos/docs/
• Format: JSON
• Authentication: None (public data)

e-Cidadania (Web Scraping)

• Website: e-Cidadania
• Content: Public consultations, legislative ideas, interactive events
• Method: HTML scraping with rate limiting (1 req/sec) and caching (15min - 24h)
• Fallback: If e-Cidadania is unavailable, API tools continue working

Bill Types (Tipos de Matéria)

📄 License

MIT

Author

Sidney da Silva Pereira Bissoli

Repository

https://github.com/SidneyBissoli/senado-br-mcp

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

1.1.0

• Added e-Cidadania integration (11 new tools).
• Web scraping infrastructure with rate limiting and caching.
• Public consultations analysis (polarized/consensual).
• Legislative ideas tracking.
• Interactive events monitoring.
• Survey topic suggestion tool.

1.0.0

• Initial release.
• 22 tools for Senate data access.
• Senators, bills, votes, committees, agenda, and lookup tools.