Senado BR

You can access Brazilian Senate open data through a Model Context Protocol (MCP) server that offers structured conversations with AI. You can use it either locally via a command line interface (stdio mode) or remotely over HTTP (cloud), giving you 33 tools to query senators, bills, votes, committees, and more in real time.

How to use

Choose your preferred connection method. If you want a local setup, run via stdio using a package runner. If you prefer a cloud-based experience, connect remotely over HTTP to the designated MCP URL. Both methods expose the same 33 tools for accessing Senate data.

How to install

Prerequisites you need before installation include Node.js 18 or newer and npm. The following steps describe how to install and run the MCP server in both local (stdio) and remote (HTTP) configurations.

Additional configurations and usage notes

Two access modes are supported: stdio (npm) for local usage and HTTP remote for cloud access. The HTTP server provides endpoints to retrieve server info, health status, usage statistics, and the MCP protocol endpoint. Rate limiting applies to the HTTP server to stay within free tier usage, with alerts at 50%, 80%, and 100% of the monthly limit. If you reach the limit, switch to the stdio version. The system uses real-time data from official sources and e-Cidadania data via web scraping with caching and rate limiting.

Security and reliability notes

Data is sourced from public APIs and compliant scraping processes. When e-Cidadania data is temporarily unavailable, other API tools (such as senators, bills, and votes) continue to function. No authentication is required for public data access.

Examples of common usage

# List senators from São Paulo using stdio mode
Use senado_listar_senadores with uf: "SP"

Troubleshooting tips

If you encounter rate limit warnings on the HTTP server, switch to the stdio mode by running the local npm-based version. Ensure you are hitting the correct MCP URL and that your client is sending valid MCP requests.

Notes on data sources

Official API: Senado Federal - Dados Abertos provides the data. e-Cidadania offers citizen participation data via web scraping, with rate limiting and caching to maintain performance.

Tool usage overview

You can access a broad set of capabilities such as listing senators, obtaining senator details, searching by name, retrieving voting histories, querying legislative texts and votes, inspecting committee activities, and exploring e-Cidadania data like public consultations, ideas, and events. The following sections enumerate the available tools in detail.

Available tools

senado_listar_senadores

List senators in office or by legislature with filters for state (UF) and party.

senado_obter_senador

Get detailed information about a senator including biography, mandates, and committees.

senado_buscar_senador_por_nome

Search senators by name.

senado_votacoes_senador

List how a senator voted with optional filters for year and date range.

senado_buscar_materias

Search bills by type (PEC, PL, PLP, MPV), number, year, keyword, or author.

senado_obter_materia

Get details of a bill including summary, author, status, and rapporteur.

senado_tramitacao_materia

Get the procedural history of a bill.

senado_textos_materia

Retrieve bill texts (original, substitute, final) with download URLs.

senado_votos_materia

Obtain voting results for a bill.

senado_listar_votacoes

List plenary votes by year with optional month and date range filters.

senado_obter_votacao

Get vote details with nominal votes by senator.

senado_votacoes_recentes

Get recent votes within the last N days.

senado_listar_comissoes

List committees with filters for type, activity, and status.

senado_obter_comissao

Get committee details including president, vice-president, and purpose.

senado_membros_comissao

List committee members with roles.

senado_reunioes_comissao

List committee meetings with agenda.

senado_agenda_plenario

Get plenary session schedule including voting agenda.

senado_agenda_comissoes

Get schedule of committee meetings.

senado_legislatura_atual

Get current legislature information such as number and dates.

senado_tipos_materia

List valid bill types (PEC, PL, PLP, MPV, etc.).

senado_partidos

List parties with senator counts.

senado_ufs

List states with senator counts.

senado_ecidadania_listar_consultas

List public consultations with citizen voting on pending bills.

senado_ecidadania_obter_consulta

Get details of a public consultation including votes and comments.

senado_ecidadania_consultas_polarizadas

Get polarized consultations indicating divisive issues.

senado_ecidadania_consultas_consensuais

Get consensual consultations showing broad agreement.

senado_ecidadania_listar_ideias

List citizen-proposed legislative ideas.

senado_ecidadania_obter_ideia

Get details of an idea including description and potential to convert to a bill.

senado_ecidadania_ideias_populares

Get the most supported legislative ideas.

senado_ecidadania_listar_eventos

List interactive events such as hearings and livestreams.

senado_ecidadania_obter_evento

Get event details including agenda, guests, and video link.

senado_ecidadania_eventos_populares

Identify events with the most citizen comments and questions.

senado_ecidadania_sugerir_tema_enquete

AI-assisted analysis to suggest topics for monthly surveys based on participation metrics.