GovQL

govql-mcp-server

适用于 GovQL 的 MCP（Model Context Protocol）服务——让 Claude Desktop、Claude Code 和 Cursor 等 AI 客户端无需自行编写 HTTP 连接代码，即可直接访问美国国会 GraphQL API：api.govql.us/graphql。

有关设计理念（为何选择 FastMCP-Python、直通式与精选式相结合的理念，以及截至 v0.4 的路线图），请参阅 design.md。

可以用它做什么

向 Agent 提问，例如：

• “佛蒙特州的两位参议员最近一次提名投票时是怎么投的？”
• “第 118 届国会期间，哪些议员曾更换党派？”
• “谁代表亚利桑那州第 3 国会选区？”
• “对比 Sanders 参议员和 Murkowski 参议员在最近一届国会中的 cloture 投票记录。”
• “在本届国会中，哪些民主党人最常与共和党人投票一致？”

Agent 会选择合适的工具，根据实时架构编写 GraphQL 查询并解析响应——无需手动处理 API。

安装

该服务通过标准输入输出，以独立子进程的方式为每个客户端运行。请选择你的客户端：

Claude Desktop

编辑 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "govql": {
      "command": "uvx",
      "args": ["govql-mcp-server"]
    }
  }
}

重启 Claude Desktop。govql 工具会显示在工具面板中。

Claude Code

将以下内容添加到项目中的 .mcp.json（或添加到全局配置 ~/.mcp.json）：

{
  "mcpServers": {
    "govql": {
      "command": "uvx",
      "args": ["govql-mcp-server"]
    }
  }
}

Cursor

Settings → MCP → Add Server。使用与上方相同的 command / args。

其他客户端

任何支持标准输入输出服务的 MCP 兼容客户端都可以使用。命令为 uvx govql-mcp-server，无需提供参数。

工具

工具	用途
execute_graphql	对 GovQL 端点运行任意 GraphQL 查询。返回查询结果以及 last_ingest 时间戳，供 Agent 判断数据的新鲜度。
list_types	返回 GovQL 架构中所有类型的名称和种类。可选的 kind 筛选器（"OBJECT"、"INPUT_OBJECT"、"ENUM" 等）可进一步缩小范围。如果不清楚可以查询哪些内容，请从这里开始。
describe_type	返回一个类型的完整详情——字段、参数签名、输入字段和枚举值。调用 list_types 后，可使用此工具了解特定类型的结构，再编写查询。
find_legislator	当你不知道议员的 bioguide id 时，可按姓名、党派、州、议院或选区查找议员。党派／州／议院／选区会按议员任期进行匹配（选区仅适用于众议院）；current_only（默认值）会将结果限制为在任议员。返回精简列表——每位议员的 bioguideId 以及当前党派／州／议院／选区。
find_vote	按类别、议院或国会届次浏览唱名投票（按时间从新到旧），或通过关键词搜索投票的 question。topic 会匹配问题文本（其中包含法案简称），而不是完整的主题索引，因此无法查到程序性投票；法案主题目前也尚未填充。返回包含每个 voteId 的精简列表。
get_legislator	根据 bioguide id 获取一位议员的完整详情：姓名、简介以及完整任期历史（不同时期的党派／州／议院／选区），并包含 current 区块。
get_vote_with_positions	根据 id 获取一项投票及其计票结果和按党派划分的明细；还可选取各议员的投票立场（按党派／州／立场筛选）。
get_voting_record	根据预计算的汇总数据，获取一位议员每届国会的投票行为：参与率和党派忠诚度。
compare_voters	按国会届次和议院对比两位议员投票一致的频率，并提供一致率。
find_party_defectors	查找在某届国会中最少与本党多数派投票一致的议员；可选按党派／议院筛选。

配置

所有环境变量均为可选项——该软件包对最终用户来说无需配置。

环境变量	默认值	用途
GOVQL_ENDPOINT	https://api.govql.us/graphql	要查询的端点。可覆盖此值以指向本地开发堆栈。
GOVQL_TIMEOUT_MS	30000	每次请求的 HTTP 超时时间。
LOG_LEVEL	INFO	日志级别。日志仅输出到 stderr（stdout 保留给 MCP 传输使用）。

限制（由上游 API 强制执行）

• 最大查询深度：10
• 最大查询复杂度：约 100 亿点（first: N 会将子级开销乘以 N——对于嵌套较深的查询，请合理设置分页大小）
• 速率限制：每个源 IP 每 60 秒 100 次请求

深度或复杂度超出限制时，工具响应中会出现 GraphQL errors 条目，以便 Agent 调整查询后重试。

数据新鲜度

每个 execute_graphql 响应都包含一个 ISO 格式的 last_ingest 时间戳。 投票数据每小时刷新一次；议员数据每天刷新一次。

状态

截至 0.4.0，该服务提供三个基础工具（execute_graphql、 list_types、describe_type），以及精选的发现工具 （find_legislator、find_vote）、单实体详情工具（get_legislator、 get_vote_with_positions）和分析工具（get_voting_record、 compare_voters、find_party_defectors）——精选的发现、详情和分析工具集现已完备。其余的 most_agreeing_pairs 和法案／委员会工具计划在 v0.4 之后推出：法案／委员会工具仍需等待 GovQL 填充数据，而 most_agreeing_pairs 则仍需等待服务端实现跨党派排名聚合——请参阅 design.md。

链接

• GovQL 项目网站
• GraphQL API
• 源代码／问题反馈