Us Race Matchups

@pipeworx/us-race-matchups

美国众议院选区或参议院席位有哪些候选人：现任议员、每位在 FEC 注册的候选人及其背后的资金、哪些人赢得了初选，以及初选和大选日期。专为 2026 年中期选举打造（大选日期为 2026 年 11 月 3 日）；适用于任何偶数年选举周期。

属于 Pipeworx — 一个将 AI Agent 连接到 1858+ 个实时数据源的 MCP 网关。这是一个独立的非官方集成，与上游提供方无关联、未经其认可，也未由其发布。

工具

• race_matchup(state, office, district?, cycle?, special?) — 单场选举。返回现任议员、候选人（党派、是否为现任、总收入、支出、手头现金、每位候选人资金统计截至日期、won_primary）、包含得票数和占比的初选结果表，以及初选、决选和大选日期。没有候选人的选区会返回错误，并列出确有候选人的选区；该选举周期没有参议院选举的州会明确说明；没有初选结果表的选举会在 primary_results_note 中说明，而不会返回空列表。
• list_races(state, office?, cycle?) — 某州的所有选举，包括注册候选人人数和现任议员。可用它查找选区编号。

身份验证

平台密钥（网关已为 FEC pack 持有的共享 data.gov 密钥）。调用方无需传入任何内容。

数据来源

• FEC，候选人和委员会申报 — 候选人、党派、是否为现任、收入、支出、手头现金。联邦公开记录。
• FEC，选举日历 — 初选、决选和大选日期。
• Wikipedia，2026 年选举页面 — 初选得票数及哪些候选人晋级。此来源由志愿者整理，并非官方来源；每条响应都会标注此信息，并列出页面引用的州选举机构（例如“Iowa Secretary of State”）。初选数据仅供参考；重要事项请向州选举机构核实。

以下细节可避免后来者重复摸索：

• FEC 资金视图不会列出没有财务摘要记录的注册人；此类候选人会显示 financials_on_file: false，资金字段为 null（不是零）。
• won_primary 是推断得出的，并非通过 ID 关联：初选表不包含 FEC ID，因此会按姓氏和党派匹配申报人；如果有多个匹配项，则进一步按名字筛选。won_primary_match 会说明匹配方式（inferred_by_surname_and_party、no_match、ambiguous）；如果无法区分两个申报人，won_primary 为 null。没有匹配字段的 null 表示未找到初选结果表。
• incumbent 是 FEC 标记的现任公职人员，不一定会出现在选票上。请查看 seeking_reelection 和 incumbent_note：如果 FEC 将所有申报人都归类为“Open seat”，则现任议员不是候选人。
• 一个人可能拥有多个 FEC 候选人 ID。race_matchup 会将其合并为一名候选人（主记录 = 最近提交申报的注册记录；其他记录列在 other_fec_registrations 下，资金不合并）；list_races 统计的是人数，而非 ID 数量。
• FEC 列出的部分候选人数据涵盖日期在未来；这些日期会显示为 null，且不会纳入 data_as_of。
• 大州的 Wikipedia 选举信息可能分散在按选区范围划分的子页面中（如 California）；此 pack 会跟进相应链接。
• Ohio 和 Florida 在 2026 年都有常规参议院选举和特别参议院选举。FEC 将两者按州归类；special: true 会读取特别选举的初选页面。
• 不提供家庭住址或其他个人联系方式。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "us-race-matchups": {
      "url": "https://gateway.pipeworx.io/us-race-matchups/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/us-race-matchups/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 和其他全网关工具集中的工具。因此，你看到的工具数量会多于表格中的数量：目前，单个数据包端点除了自身工具外，还会列出大约 30 个共享工具。连接的 initialize 响应会说明其确切范围，也是当天有效范围的权威信息。

这是有意为之，并非意外多路复用。元工具可以让限定范围的连接回答本数据包未涵盖的问题——通过 ask_pipeworx 跨整个目录进行路由——无需添加第二个 MCP 服务。目前无法挂载不包含这些元工具的数据包端点；如果额外的模式消耗的上下文多于路由带来的价值，请连接一次完整网关，而不是连接多个数据包端点。

或者连接完整的 Pipeworx 网关，直接列出所有数据包的工具，而不仅仅是此数据包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都连接到同一个网关和同一组 1858+ 个数据源。唯一的区别是直接列出哪个数据包的工具；无论连接哪一个，ask_pipeworx 都能访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/race_matchup \
  -H 'Content-Type: application/json' \
  -d '{"state":"IA","office":"house","district":1}'

首次调用无需账户。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/race_matchup。查找工具：使用 {"query":"..."} 向 https://gateway.pipeworx.io/v1/tools/search_packs 发送 POST 请求。

通过 npm 运行

@pipeworx/mcp-us-race-matchups 是一个连接到 Pipeworx 网关的本地 stdio 桥接程序：MCP 客户端通过 npx 启动它，它会将每次调用转发到上文所示的同一个 https://gateway.pipeworx.io/us-race-matchups/mcp 端点。它需要网络访问；没有离线模式。

{
  "mcpServers": {
    "us-race-matchups": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-us-race-matchups"]
    }
  }
}

不使用密钥时，它会匿名调用，每天最多 50 次。免费账户可将上限提高到每天 200 次：在 https://pipeworx.io/signup 获取密钥，并将 "env": { "PIPEWORX_API_KEY": "<your key>" } 添加到服务条目中。 密钥会作为 Bearer 令牌发送，与托管连接的发送方式相同，因此调用会按相同方式计量和计费。

默认情况下，它仅列出此数据包的工具。设置 PIPEWORX_META_TOOLS=1，也会列出 ask_pipeworx 和其他全网关工具。

使用 HTTPS 代理时：Node 内置的 fetch 默认不会读取 HTTPS_PROXY。较新的 Node 版本在设置 NODE_USE_ENV_PROXY=1 后会遵循该变量；请查阅对应 Node 版本的文档。

使用 ask_pipeworx

你可以不用直接调用工具，而是用通俗的英语提问——这既适用于上面的数据包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Us Race Matchups data" })

网关会选择合适的工具并自动填写参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT