{
  "markdown": "> # ⚠️ Deprecated — this repository has moved\n>\n> This server is **no longer maintained here.** The Brazilian Senate MCP server now lives at\n> **[senado-br-mcp-cloudflare](https://github.com/SidneyBissoli/senado-br-mcp-cloudflare)** — **66 tools**\n> with level-1 **provenance**, available both **hosted** (`https://senado.sidneybissoli.com/mcp`, no setup)\n> and via **npm/stdio** (`npx senado-br-mcp`, v3.x). The npm package **`senado-br-mcp` now publishes that\n> server** (v3.2.1+); versions `< 3.0.0` here are deprecated. Please migrate — this repository is archived.\n\n---\n\n# Senado Brasil MCP Server\n\n[![npm version](https://img.shields.io/npm/v/senado-br-mcp.svg)](https://www.npmjs.com/package/senado-br-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/senado-br-mcp.svg)](https://www.npmjs.com/package/senado-br-mcp)\n[![node](https://img.shields.io/node/v/senado-br-mcp)](https://www.npmjs.com/package/senado-br-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)\n[![GitHub stars](https://img.shields.io/github/stars/SidneyBissoli/senado-br-mcp?style=flat&logo=github)](https://github.com/SidneyBissoli/senado-br-mcp)\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/SidneyBissoli?logo=githubsponsors&label=Sponsor&color=db61a2)](https://github.com/sponsors/SidneyBissoli)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n🇧🇷 [Leia em Português](README.pt-BR.md)\n\nMCP server for Brazilian Federal Senate open data (legislators, bills, votes, committees).\n\nServidor MCP (Model Context Protocol) que permite acesso estruturado aos dados abertos do Senado Federal do Brasil, democratizando o acesso a informações legislativas através de conversas com IA.\n\n## See it in action\n\nAsk your assistant, in plain Portuguese:\n\n- *\"Liste os senadores de SP em exercício.\"* → `senado_listar_senadores`\n- *\"Mostre a tramitação da PEC 45/2019.\"* → `senado_buscar_materias` + `senado_obter_materia`\n- *\"Quais ideias legislativas mais apoiadas estão abertas no e-Cidadania?\"* → `senado_ecidadania_listar_ideias`\n\nThe answers come live from the Senate's official open-data APIs — real data with provenance, not numbers guessed from training data.\n\n## Features\n\n- **33 tools** for accessing Senate data\n- Real-time data from official API\n- **e-Cidadania integration**: citizen participation data via web scraping\n- Structured JSON responses\n- Error handling with actionable suggestions\n- TypeScript with full type safety\n- **Two access modes:** stdio (npm) and HTTP remote\n\n## Two Ways to Use\n\n| Mode | Installation | Best For |\n|------|--------------|----------|\n| **stdio/npm** | `npx senado-br-mcp` | Technical users, local usage |\n| **HTTP remote** | None required | Non-technical users, cloud access |\n\nBoth modes provide access to the same 33 tools.\n\n---\n\n## Option 1: stdio/npm (Local)\n\n### Installation\n\n**Using npx (Recommended):**\n```bash\nnpx senado-br-mcp\n```\n\n**Global Installation:**\n```bash\nnpm install -g senado-br-mcp\nsenado-br-mcp\n```\n\n**From Source:**\n```bash\ngit clone https://github.com/SidneyBissoli/senado-br-mcp.git\ncd senado-br-mcp\nnpm install\nnpm run build\nnpm start\n```\n\n### Claude Desktop Configuration\n\nAdd to your `claude_desktop_config.json`:\n\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"senado-br-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"senado-br-mcp\"]\n    }\n  }\n}\n```\n\n---\n\n## Option 2: HTTP Remote (Cloud)\n\nNo installation required. Connect directly via URL.\n\n### Claude Desktop Configuration\n\nIn Claude Desktop settings, go to **\"Add Custom Connector\"** and enter:\n\n- **Name:** senado-br-mcp\n- **URL:** `https://senado-br-mcp.up.railway.app/mcp`\n\n### Endpoints\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /` | Server info and documentation |\n| `GET /health` | Health check |\n| `GET /stats` | Usage statistics |\n| `POST /mcp` | MCP protocol endpoint |\n\n### Rate Limiting\n\nThe HTTP server has a monthly request limit to stay within free tier:\n- Alerts are sent at 50%, 80%, and 100% usage\n- When limit is reached, use the npm version instead\n- Limit resets on the 1st of each month\n\n## Available Tools\n\n### Senators (Senadores)\n\n| Tool | Description |\n|------|-------------|\n| `senado_listar_senadores` | List senators in office or by legislature. Filters: state (UF), party |\n| `senado_obter_senador` | Get detailed info about a senator (biography, mandates, committees) |\n| `senado_buscar_senador_por_nome` | Search senators by name |\n| `senado_votacoes_senador` | List how a senator voted. Filters: year, date range |\n\n### Legislative Matters (Matérias)\n\n| Tool | Description |\n|------|-------------|\n| `senado_buscar_materias` | Search bills by type (PEC, PL, PLP, MPV), number, year, keyword, author |\n| `senado_obter_materia` | Get bill details (summary, author, status, rapporteur) |\n| `senado_tramitacao_materia` | Get bill's procedural history |\n| `senado_textos_materia` | Get bill texts (original, substitute, final) with download URLs |\n| `senado_votos_materia` | Get voting results for a bill |\n\n### Votes (Votações)\n\n| Tool | Description |\n|------|-------------|\n| `senado_listar_votacoes` | List plenary votes by year. Filters: month, date range |\n| `senado_obter_votacao` | Get vote details with nominal votes by senator |\n| `senado_votacoes_recentes` | Get recent votes (last N days) |\n\n### Committees (Comissões)\n\n| Tool | Description |\n|------|-------------|\n| `senado_listar_comissoes` | List committees. Filters: type (permanent, temporary, CPI), active |\n| `senado_obter_comissao` | Get committee details (president, vice-president, purpose) |\n| `senado_membros_comissao` | List committee members with roles |\n| `senado_reunioes_comissao` | List committee meetings with agenda |\n\n### Agenda\n\n| Tool | Description |\n|------|-------------|\n| `senado_agenda_plenario` | Get plenary session schedule with voting agenda |\n| `senado_agenda_comissoes` | Get committee meeting schedule |\n\n### Lookup/Auxiliary (Auxiliares)\n\n| Tool | Description |\n|------|-------------|\n| `senado_legislatura_atual` | Get current legislature info (number, period, dates) |\n| `senado_tipos_materia` | List valid bill types (PEC, PL, PLP, MPV, etc.) |\n| `senado_partidos` | List parties with senator count |\n| `senado_ufs` | List states with senator count |\n\n### e-Cidadania (Citizen Participation)\n\nTools for accessing e-Cidadania data - the Senate's citizen participation platform.\n\n#### Public Consultations (Consultas Públicas)\n\n| Tool | Description |\n|------|-------------|\n| `senado_ecidadania_listar_consultas` | List public consultations with citizen voting on pending bills |\n| `senado_ecidadania_obter_consulta` | Get consultation details including votes, author, and comments |\n| `senado_ecidadania_consultas_polarizadas` | Get polarized consultations (~50/50 votes) - useful for identifying divisive issues |\n| `senado_ecidadania_consultas_consensuais` | Get consensual consultations (>85% one way) - identifies broad agreement |\n\n#### Legislative Ideas (Ideias Legislativas)\n\n| Tool | Description |\n|------|-------------|\n| `senado_ecidadania_listar_ideias` | List citizen-proposed legislative ideas |\n| `senado_ecidadania_obter_ideia` | Get idea details including full description and conversion to bill |\n| `senado_ecidadania_ideias_populares` | Get most supported legislative ideas |\n\n#### Interactive Events (Eventos Interativos)\n\n| Tool | Description |\n|------|-------------|\n| `senado_ecidadania_listar_eventos` | List interactive events (hearings, confirmations, livestreams) |\n| `senado_ecidadania_obter_evento` | Get event details including agenda, guests, and video link |\n| `senado_ecidadania_eventos_populares` | Get events with most citizen comments and questions |\n\n#### Analysis Tools\n\n| Tool | Description |\n|------|-------------|\n| `senado_ecidadania_sugerir_tema_enquete` | AI-assisted analysis to suggest topics for monthly surveys based on participation metrics |\n\n> **Note:** e-Cidadania tools use web scraping with rate limiting and caching. If the e-Cidadania website is temporarily unavailable, API tools (senators, bills, votes) remain operational.\n\n## Usage Examples\n\n### List senators from São Paulo\n\n```\nUse senado_listar_senadores with uf: \"SP\"\n```\n\n### Search for Constitutional Amendments in 2024\n\n```\nUse senado_buscar_materias with sigla: \"PEC\", ano: 2024\n```\n\n### Get recent votes\n\n```\nUse senado_votacoes_recentes with dias: 7\n```\n\n### Find a senator by name\n\n```\nUse senado_buscar_senador_por_nome with nome: \"Randolfe\"\n```\n\n### Get CCJ committee members\n\n```\nUse senado_membros_comissao with sigla: \"CCJ\"\n```\n\n### Get polarized public consultations\n\n```\nUse senado_ecidadania_consultas_polarizadas with minimoVotos: 5000\n```\n\n### Get most supported citizen ideas\n\n```\nUse senado_ecidadania_ideias_populares with limite: 5\n```\n\n### Find upcoming interactive events\n\n```\nUse senado_ecidadania_listar_eventos with status: \"agendado\"\n```\n\n## Response Format\n\nAll tools return structured JSON responses:\n\n### Success Response\n\n```json\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"metadata\": {\n    \"fonte\": \"Senado Federal - Dados Abertos\",\n    \"dataConsulta\": \"2024-01-15T10:30:00Z\",\n    \"endpoint\": \"/senador/lista/atual\"\n  }\n}\n```\n\n### Error Response\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SENADOR_NAO_ENCONTRADO\",\n    \"message\": \"Senator with code 99999 was not found\",\n    \"suggestion\": \"Use senado_buscar_senador_por_nome to find the correct code\"\n  }\n}\n```\n\n## Development\n\n### Prerequisites\n\n- Node.js 18+\n- npm\n\n### Setup\n\n```bash\nnpm install\n```\n\n### Build\n\n```bash\n# Build stdio version (npm package)\nnpm run build\n\n# Build HTTP server version\nnpm run build:server\n\n# Build both\nnpm run build:all\n```\n\n### Development Mode\n\n```bash\n# stdio mode\nnpm run dev\n\n# HTTP server mode\nnpm run dev:server\n```\n\n### Type Check\n\n```bash\nnpm run typecheck\n```\n\n### Test with MCP Inspector\n\n```bash\nnpm run inspect\n```\n\n---\n\n## Self-Hosting HTTP Server\n\nYou can host your own HTTP server instance.\n\n### Local\n\n```bash\nnpm run build:server\nnpm run start:server\n# Server runs on http://localhost:3000\n```\n\n### Railway\n\n1. Fork this repository\n2. Connect Railway to your GitHub\n3. Deploy (auto-detects configuration from `railway.json`)\n4. Set environment variables:\n   - `MONTHLY_REQUEST_LIMIT` (default: 10000)\n   - `ALERT_WEBHOOK_URL` (optional, for notifications)\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PORT` | Server port | 3000 |\n| `MONTHLY_REQUEST_LIMIT` | Monthly request limit | 10000 |\n| `ALERT_WEBHOOK_URL` | Webhook for alerts | - |\n| `LOG_LEVEL` | Logging level | info |\n\n## Data Sources\n\n### Official API\n- **API**: [Senado Federal - Dados Abertos](https://legis.senado.leg.br/dadosabertos)\n- **Documentation**: https://legis.senado.leg.br/dadosabertos/docs/\n- **Format**: JSON\n- **Authentication**: None (public data)\n\n### e-Cidadania (Web Scraping)\n- **Website**: [e-Cidadania](https://www12.senado.leg.br/ecidadania)\n- **Content**: Public consultations, legislative ideas, interactive events\n- **Method**: HTML scraping with rate limiting (1 req/sec) and caching (15min-24h)\n- **Fallback**: If e-Cidadania is unavailable, API tools continue working\n\n## Bill Types (Tipos de Matéria)\n\n| Code | Name | Description |\n|------|------|-------------|\n| PEC | Proposta de Emenda à Constituição | Constitutional Amendment |\n| PL | Projeto de Lei | Ordinary Law Bill |\n| PLP | Projeto de Lei Complementar | Complementary Law Bill |\n| MPV | Medida Provisória | Provisional Measure |\n| PDL | Projeto de Decreto Legislativo | Legislative Decree Bill |\n| PRS | Projeto de Resolução do Senado | Senate Resolution Bill |\n| PLC | Projeto de Lei da Câmara | Chamber of Deputies Bill |\n\n## License\n\nMIT\n\n## Author\n\nSidney da Silva Pereira Bissoli\n\n## Repository\n\nhttps://github.com/SidneyBissoli/senado-br-mcp\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Changelog\n\n### 1.1.0\n\n- Added e-Cidadania integration (11 new tools)\n- Web scraping infrastructure with rate limiting and caching\n- Public consultations analysis (polarized/consensual)\n- Legislative ideas tracking\n- Interactive events monitoring\n- Survey topic suggestion tool\n\n### 1.0.0\n\n- Initial release\n- 22 tools for Senate data access\n- Senators, bills, votes, committees, agenda, and lookup tools\n",
  "bytes": 12532,
  "sha": "e0b1bd3d2a43b7358a951744846280a6a22f616a0544d487d94e023b2888a3f6",
  "repo_slug": "sidneybissoli/senado-br-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sidneybissoli_senado_br_mcp_de053b78/readme"
}