senado-br-mcp

🚀 巴西联邦参议院MCP服务器

本项目是一个MCP（模型上下文协议）服务器，可对巴西联邦参议院的开放数据（包括立法者、法案、投票、委员会等信息）进行结构化访问。通过与人工智能对话，它让立法信息的获取变得更加民主。

🚀 快速开始

该项目提供了两种使用模式，分别为stdio/npm（本地）和HTTP远程（云端），两种模式均可访问33种工具。

✨ 主要特性

• 33种工具：用于访问参议院数据。
• 实时数据：数据来源于官方API。
• e-Cidadania集成：通过网页抓取获取公民参与数据。
• 结构化JSON响应：方便数据处理。
• 错误处理：提供可操作的建议。
• TypeScript编写：具备完整的类型安全。
• 两种访问模式：stdio（npm）和HTTP远程。

📦 安装指南

Option 1: stdio/npm（本地）

安装

• 使用npx（推荐）：

npx senado-br-mcp

• 全局安装：

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

• 从源代码安装：

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

Claude桌面配置

将以下内容添加到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远程（云端）

无需安装，可直接通过URL连接。

Claude桌面配置

在Claude桌面设置中，点击**"添加自定义连接器"**，并输入以下信息：

• 名称：senado-br-mcp
• URL：https://senado-br-mcp.up.railway.app/mcp

端点

| 端点 | 描述 | |------|------| | GET / | 服务器信息和文档 | | GET /health | 健康检查 | | GET /stats | 使用统计 | | POST /mcp | MCP协议端点 |

速率限制

HTTP服务器有每月请求限制，以保持在免费套餐范围内：

• 在使用量达到50%、80%和100%时会发送警报。
• 达到限制后，请使用npm版本。
• 限制每月1号重置。

💻 使用示例

列出圣保罗州的参议员

Use senado_listar_senadores with uf: "SP"

搜索2024年的宪法修正案

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

获取近期投票信息

Use senado_votacoes_recentes with dias: 7

按姓名查找参议员

Use senado_buscar_senador_por_nome with nome: "Randolfe"

获取CCJ委员会成员

Use senado_membros_comissao with sigla: "CCJ"

获取两极分化的公众咨询

Use senado_ecidadania_consultas_polarizadas with minimoVotos: 5000

获取最受支持的公民提案

Use senado_ecidadania_ideias_populares with limite: 5

查找即将举行的互动活动

Use senado_ecidadania_listar_eventos with status: "agendado"

📚 详细文档

可用工具

参议员（Senadores）

| 工具 | 描述 | |------|------| | senado_listar_senadores | 列出在职或按立法期列出参议员。可按州（UF）、政党过滤 | | senado_obter_senador | 获取参议员的详细信息（传记、任期、委员会） | | senado_buscar_senador_por_nome | 按姓名搜索参议员 | | senado_votacoes_senador | 列出参议员的投票情况。可按年份、日期范围过滤 |

立法事务（Matérias）

| 工具 | 描述 | |------|------| | senado_buscar_materias | 按类型（PEC、PL、PLP、MPV）、编号、年份、关键词、作者搜索法案 | | senado_obter_materia | 获取法案详细信息（摘要、作者、状态、报告人） | | senado_tramitacao_materia | 获取法案的程序历史 | | senado_textos_materia | 获取法案文本（原始、替代、最终）及下载链接 | | senado_votos_materia | 获取法案的投票结果 |

投票（Votações）

| 工具 | 描述 | |------|------| | senado_listar_votacoes | 按年份列出全体会议投票。可按月份、日期范围过滤 | | senado_obter_votacao | 获取投票详细信息，包括参议员的记名投票 | | senado_votacoes_recentes | 获取近期投票（过去N天） |

委员会（Comissões）

| 工具 | 描述 | |------|------| | senado_listar_comissoes | 列出委员会。可按类型（常设、临时、CPI）、是否活跃过滤 | | senado_obter_comissao | 获取委员会详细信息（主席、副主席、目的） | | senado_membros_comissao | 列出委员会成员及其角色 | | senado_reunioes_comissao | 列出委员会会议及议程 |

议程

| 工具 | 描述 | |------|------| | senado_agenda_plenario | 获取全体会议日程及投票议程 | | senado_agenda_comissoes | 获取委员会会议日程 |

查找/辅助（Auxiliares）

| 工具 | 描述 | |------|------| | senado_legislatura_atual | 获取当前立法期信息（编号、周期、日期） | | senado_tipos_materia | 列出有效的法案类型（PEC、PL、PLP、MPV等） | | senado_partidos | 列出政党及参议员数量 | | senado_ufs | 列出各州及参议员数量 |

e-Cidadania（公民参与）

用于访问e-Cidadania数据（参议院的公民参与平台）的工具。

公众咨询（Consultas Públicas）

| 工具 | 描述 | |------|------| | senado_ecidadania_listar_consultas | 列出对未决法案进行公民投票的公众咨询 | | senado_ecidadania_obter_consulta | 获取咨询详细信息，包括投票、作者和评论 | | senado_ecidadania_consultas_polarizadas | 获取两极分化的咨询（约50/50投票） - 有助于识别有争议的问题 | | senado_ecidadania_consultas_consensuais | 获取达成共识的咨询（某一方超过85%） - 识别广泛的共识 |

立法提案（Ideias Legislativas）

| 工具 | 描述 | |------|------| | senado_ecidadania_listar_ideias | 列出公民提出的立法提案 | | senado_ecidadania_obter_ideia | 获取提案详细信息，包括完整描述和转化为法案的情况 | | senado_ecidadania_ideias_populares | 获取最受支持的立法提案 |

互动活动（Eventos Interativos）

| 工具 | 描述 | |------|------| | senado_ecidadania_listar_eventos | 列出互动活动（听证会、确认会、直播） | | senado_ecidadania_obter_evento | 获取活动详细信息，包括议程、嘉宾和视频链接 | | senado_ecidadania_eventos_populares | 获取公民评论和问题最多的活动 |

分析工具

| 工具 | 描述 | |------|------| | senado_ecidadania_sugerir_tema_enquete | 基于参与指标，通过AI辅助分析建议月度调查主题 |

响应格式

所有工具均返回结构化的JSON响应：

成功响应

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

错误响应

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

开发

前提条件

• Node.js 18+
• npm

安装依赖

npm install

构建

# 构建stdio版本（npm包）
npm run build

# 构建HTTP服务器版本
npm run build:server

# 构建两者
npm run build:all

开发模式

# stdio模式
npm run dev

# HTTP服务器模式
npm run dev:server

类型检查

npm run typecheck

使用MCP检查器进行测试

npm run inspect

自行托管HTTP服务器

你可以自行托管HTTP服务器实例。

本地

npm run build:server
npm run start:server
# 服务器运行在 http://localhost:3000

Railway

1. 分叉此仓库。
2. 将Railway连接到你的GitHub。
3. 部署（自动从railway.json检测配置）。
4. 设置环境变量：
   • MONTHLY_REQUEST_LIMIT（默认值：10000）
   • ALERT_WEBHOOK_URL（可选，用于通知）

环境变量

| 变量 | 描述 | 默认值 | |------|------|--------| | PORT | 服务器端口 | 3000 | | MONTHLY_REQUEST_LIMIT | 每月请求限制 | 10000 | | ALERT_WEBHOOK_URL | 警报Webhook | - | | LOG_LEVEL | 日志级别 | info |

数据源

官方API

• API：Senado Federal - Dados Abertos
• 文档：https://legis.senado.leg.br/dadosabertos/docs/
• 格式：JSON
• 认证：无（公共数据）

e-Cidadania（网页抓取）

• 网站：e-Cidadania
• 内容：公众咨询、立法提案、互动活动
• 方法：HTML抓取，有速率限制（1请求/秒）和缓存（15分钟 - 24小时）
• 备用方案：如果e-Cidadania不可用，API工具仍可正常工作。

法案类型（Tipos de Matéria）

| 代码 | 名称 | 描述 | |------|------|------| | PEC | Proposta de Emenda à Constituição | 宪法修正案 | | PL | Projeto de Lei | 普通法律法案 | | PLP | Projeto de Lei Complementar | 补充法律法案 | | MPV | Medida Provisória | 临时措施 | | PDL | Projeto de Decreto Legislativo | 立法法令法案 | | PRS | Projeto de Resolução do Senado | 参议院决议法案 | | PLC | Projeto de Lei da Câmara | 众议院法案 |

📄 许可证

本项目采用MIT许可证。

作者

Sidney da Silva Pereira Bissoli

仓库

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

贡献

欢迎贡献代码！请随时提交拉取请求。

更新日志

1.1.0

• 添加e-Cidadania集成（11个新工具）
• 具备速率限制和缓存的网页抓取基础设施
• 公众咨询分析（两极分化/达成共识）
• 立法提案跟踪
• 互动活动监控
• 调查主题建议工具

1.0.0

• 初始版本
• 22个用于访问参议院数据的工具
• 参议员、法案、投票、委员会、议程和查找工具