senado-br-mcp

MCP Server para dados abertos do Senado Federal Brasileiro - legisladores, projetos de lei, votações, comissões

GitHub

Documentação

⚠️ Obsoleto — este repositório foi movido

Este servidor não é mais mantido aqui. O servidor MCP do Senado Brasileiro agora está em senado-br-mcp-cloudflare — 66 ferramentas com proveniência de nível 1, disponível tanto hospedado (https://senado.sidneybissoli.com/mcp, sem configuração) quanto via npm/stdio (npx senado-br-mcp, v3.x). O pacote npm senado-br-mcp agora publica esse servidor (v3.2.1+); as versões < 3.0.0 aqui estão obsoletas. Por favor, migre — este repositório está arquivado.

Servidor MCP do Senado Brasil

npm version npm downloads node MCP Registry GitHub stars GitHub Sponsors License: MIT

🇧🇷 Leia em Português

Servidor MCP para dados abertos do Senado Federal do Brasil (parlamentares, proposições, votações, comissões).

Servidor 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.

Veja em ação

Pergunte ao seu assistente, em português simples:

  • "Liste os senadores de SP em exercício." → senado_listar_senadores
  • "Mostre a tramitação da PEC 45/2019." → senado_buscar_materias + senado_obter_materia
  • "Quais ideias legislativas mais apoiadas estão abertas no e-Cidadania?" → senado_ecidadania_listar_ideias

As respostas vêm ao vivo das APIs oficiais de dados abertos do Senado — dados reais com proveniência, não números adivinhados a partir de dados de treinamento.

Recursos

  • 33 ferramentas para acesso a dados do Senado
  • Dados em tempo real da API oficial
  • Integração com e-Cidadania: dados de participação cidadã via web scraping
  • Respostas JSON estruturadas
  • Tratamento de erros com sugestões acionáveis
  • TypeScript com segurança total de tipos
  • Dois modos de acesso: stdio (npm) e HTTP remoto

Duas Formas de Uso

ModoInstalaçãoMelhor Para
stdio/npmnpx senado-br-mcpUsuários técnicos, uso local
HTTP remotoNenhuma necessáriaUsuários não técnicos, acesso em nuvem

Ambos os modos fornecem acesso às mesmas 33 ferramentas.

Opção 1: stdio/npm (Local)

Instalação

Usando npx (Recomendado):

npx senado-br-mcp

Instalação Global:

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

A partir do Código-Fonte:

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

Configuração do Claude Desktop

Adicione ao seu 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"]
    }
  }
}

Opção 2: HTTP Remoto (Nuvem)

Nenhuma instalação necessária. Conecte-se diretamente via URL.

Configuração do Claude Desktop

Nas configurações do Claude Desktop, vá em "Adicionar Conector Personalizado" e insira:

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

Endpoints

EndpointDescrição
GET /Informações do servidor e documentação
GET /healthVerificação de integridade
GET /statsEstatísticas de uso
POST /mcpEndpoint do protocolo MCP

Limite de Taxa

O servidor HTTP tem um limite mensal de requisições para permanecer no nível gratuito:

  • Alertas são enviados em 50%, 80% e 100% do uso
  • Quando o limite for atingido, use a versão npm
  • O limite é redefinido no 1º dia de cada mês

Ferramentas Disponíveis

Senadores

FerramentaDescrição
senado_listar_senadoresLista senadores em exercício ou por legislatura. Filtros: estado (UF), partido
senado_obter_senadorObtém informações detalhadas sobre um senador (biografia, mandatos, comissões)
senado_buscar_senador_por_nomeBusca senadores por nome
senado_votacoes_senadorLista como um senador votou. Filtros: ano, intervalo de datas

Matérias Legislativas

FerramentaDescrição
senado_buscar_materiasBusca proposições por tipo (PEC, PL, PLP, MPV), número, ano, palavra-chave, autor
senado_obter_materiaObtém detalhes da proposição (resumo, autor, situação, relator)
senado_tramitacao_materiaObtém o histórico processual da proposição
senado_textos_materiaObtém textos da proposição (original, substitutivo, final) com URLs de download
senado_votos_materiaObtém resultados de votação de uma proposição

Votações

FerramentaDescrição
senado_listar_votacoesLista votações em plenário por ano. Filtros: mês, intervalo de datas
senado_obter_votacaoObtém detalhes da votação com votos nominais por senador
senado_votacoes_recentesObtém votações recentes (últimos N dias)

Comissões

FerramentaDescrição
senado_listar_comissoesLista comissões. Filtros: tipo (permanente, temporária, CPI), ativa
senado_obter_comissaoObtém detalhes da comissão (presidente, vice-presidente, finalidade)
senado_membros_comissaoLista membros da comissão com funções
senado_reunioes_comissaoLista reuniões da comissão com pauta

Agenda

FerramentaDescrição
senado_agenda_plenarioObtém a programação da sessão plenária com pauta de votação
senado_agenda_comissoesObtém a programação de reuniões de comissão

Consulta/Auxiliares

FerramentaDescrição
senado_legislatura_atualObtém informações da legislatura atual (número, período, datas)
senado_tipos_materiaLista tipos válidos de proposições (PEC, PL, PLP, MPV, etc.)
senado_partidosLista partidos com contagem de senadores
senado_ufsLista estados com contagem de senadores

e-Cidadania (Participação Cidadã)

Ferramentas para acessar dados do e-Cidadania — a plataforma de participação cidadã do Senado.

Consultas Públicas

FerramentaDescrição
senado_ecidadania_listar_consultasLista consultas públicas com votação cidadã em proposições pendentes
senado_ecidadania_obter_consultaObtém detalhes da consulta, incluindo votos, autor e comentários
senado_ecidadania_consultas_polarizadasObtém consultas polarizadas (~50/50 votos) — útil para identificar questões divisivas
senado_ecidadania_consultas_consensuaisObtém consultas consensuais (>85% em uma direção) — identifica amplo acordo

Ideias Legislativas

FerramentaDescrição
senado_ecidadania_listar_ideiasLista ideias legislativas propostas por cidadãos
senado_ecidadania_obter_ideiaObtém detalhes da ideia, incluindo descrição completa e conversão em proposição
senado_ecidadania_ideias_popularesObtém ideias legislativas mais apoiadas

Eventos Interativos

FerramentaDescrição
senado_ecidadania_listar_eventosLista eventos interativos (audiências, sabatinas, transmissões ao vivo)
senado_ecidadania_obter_eventoObtém detalhes do evento, incluindo pauta, convidados e link de vídeo
senado_ecidadania_eventos_popularesObtém eventos com mais comentários e perguntas de cidadãos

Ferramentas de Análise

FerramentaDescrição
senado_ecidadania_sugerir_tema_enqueteAnálise assistida por IA para sugerir temas para enquetes mensais com base em métricas de participação

Nota: As ferramentas do e-Cidadania usam web scraping com limite de taxa e cache. Se o site do e-Cidadania estiver temporariamente indisponível, as ferramentas de API (senadores, proposições, votações) permanecem operacionais.

Exemplos de Uso

Listar senadores de São Paulo

Use senado_listar_senadores with uf: "SP"

Buscar Emendas Constitucionais em 2024

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

Obter votações recentes

Use senado_votacoes_recentes with dias: 7

Encontrar um senador por nome

Use senado_buscar_senador_por_nome with nome: "Randolfe"

Obter membros da comissão CCJ

Use senado_membros_comissao with sigla: "CCJ"

Obter consultas públicas polarizadas

Use senado_ecidadania_consultas_polarizadas with minimoVotos: 5000

Obter ideias cidadãs mais apoiadas

Use senado_ecidadania_ideias_populares with limite: 5

Encontrar eventos interativos futuros

Use senado_ecidadania_listar_eventos with status: "agendado"

Formato de Resposta

Todas as ferramentas retornam respostas JSON estruturadas:

Resposta de Sucesso

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

Resposta de Erro

{
  "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"
  }
}

Desenvolvimento

Pré-requisitos

  • Node.js 18+
  • npm

Configuração

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

Modo de Desenvolvimento

# stdio mode
npm run dev

# HTTP server mode
npm run dev:server

Verificação de Tipos

npm run typecheck

Testar com o MCP Inspector

npm run inspect

Auto-Hospedagem do Servidor HTTP

Você pode hospedar sua própria instância do servidor HTTP.

Local

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

Railway

  1. Faça um fork deste repositório
  2. Conecte o Railway ao seu GitHub
  3. Implante (detecta automaticamente a configuração do railway.json)
  4. Defina as variáveis de ambiente:
    • MONTHLY_REQUEST_LIMIT (padrão: 10000)
    • ALERT_WEBHOOK_URL (opcional, para notificações)

Variáveis de Ambiente

VariávelDescriçãoPadrão
PORTPorta do servidor3000
MONTHLY_REQUEST_LIMITLimite mensal de requisições10000
ALERT_WEBHOOK_URLWebhook para alertas-
LOG_LEVELNível de registroinfo

Fontes de Dados

API Oficial

e-Cidadania (Web Scraping)

  • Site: e-Cidadania
  • Conteúdo: Consultas públicas, ideias legislativas, eventos interativos
  • Método: Raspagem de HTML com limite de taxa (1 req/seg) e cache (15min-24h)
  • Fallback: Se o e-Cidadania estiver indisponível, as ferramentas de API continuam funcionando

Tipos de Matéria

CódigoNomeDescrição
PECProposta de Emenda à ConstituiçãoEmenda Constitucional
PLProjeto de LeiProjeto de Lei Ordinária
PLPProjeto de Lei ComplementarProjeto de Lei Complementar
MPVMedida ProvisóriaMedida Provisória
PDLProjeto de Decreto LegislativoProjeto de Decreto Legislativo
PRSProjeto de Resolução do SenadoProjeto de Resolução do Senado
PLCProjeto de Lei da CâmaraProjeto de Lei da Câmara dos Deputados

Licença

MIT

Autor

Sidney da Silva Pereira Bissoli

Repositório

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

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Histórico de Versões

1.1.0

  • Adicionada integração com e-Cidadania (11 novas ferramentas)
  • Infraestrutura de web scraping com limite de taxa e cache
  • Análise de consultas públicas (polarizadas/consensuais)
  • Acompanhamento de ideias legislativas
  • Monitoramento de eventos interativos
  • Ferramenta de sugestão de temas para enquetes

1.0.0

  • Lançamento inicial
  • 22 ferramentas para acesso a dados do Senado
  • Ferramentas de senadores, proposições, votações, comissões, agenda e consulta