Us Elections

@pipeworx/us-elections

美国选举结果——各州总统和美国参议院候选人级别的票数（所有州，1976-2024）；美国联邦选举委员会（FEC）官方按选区划分的 2020 年和 2022 年全国众议院大选结果（MEDSL 访客留言簿访问限制文件的无门槛替代方案）；以及 2024 年大选中总统、参议院和美国众议院的县级（13 个州）和选区级（宾夕法尼亚州、密歇根州）详细数据。Fleet #2952，扩展版 fleet #2958。

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

工具

• election_results(state, year, office, level?, county?, district?, limit?, offset?) — 返回一个州/年份/职位在 state、county 或 precinct 粒度（默认为 county）下的候选人级别结果。传入 county，可将县级或选区级查询限定为某个县；传入 district（例如 "09"），可将众议院选举限定为某个选区。每行包含候选人、党派、票数、该选举的总票数和得票率，以及 source、source_url、license 和 data_as_of。如果某种组合没有数据，会明确报错并指出实际存在的数据粒度，而不会返回空结果。
• election_race_summary(state, year, office) — 返回某场选举的汇总票数、得票率、胜者和差额，数据取自实际可用的最高汇总粒度（有全州数据时使用全州数据，否则汇总现有的县级/选区级详细数据）。对于选区职位（众议院），每个选区返回一条汇总结果。
• list_elections(state?) — 列出此数据包实际包含的州/年份/职位组合及其数据粒度。查询特定选举前，请先调用此工具检查覆盖范围。

州可以使用邮政缩写（"PA"）或全名（"Pennsylvania"），不区分大小写。职位可以使用 "president"、"senate" 或 "house"（也接受常见同义词，如 "POTUS"、"U.S. Senate"）。

身份验证

无需密钥。这些工具仅通过持有数据的 Pipeworx 网关提供服务；单独运行 npm install 没有可读取的数据，且所有工具在这种环境下都会抛出明确的“not bound in this runtime”错误，而不是返回空列表。

数据来源

• MIT 选举数据与科学实验室（MEDSL），Harvard Dataverse——1976-2024 年美国总统州级选举结果。
• MIT 选举数据与科学实验室（MEDSL），Harvard Dataverse——1976-2024 年美国参议院州级选举结果。 **许可：**两者均采用 CC0 1.0（公共领域奉献）。
• 联邦选举委员会（fec.gov）——官方《联邦选举》统计出版物：2020 年和 2022 年大选按选区划分的美国众议院结果。（同一出版物还包含一份参议院数据表，但此处有意不加载——上文的 MEDSL 已涵盖这些年份的参议院州级数据；如果两者都加载，election_race_summary 会重复计算每位候选人的票数。请参阅 load-data.mjs。） **许可：**公共领域（美国政府作品，17 U.S.C. 105）。无需登录、密钥或访客留言簿——数据以普通 xlsx 文件形式从 fec.gov 提供下载。
• OpenElections——2024 年大选的县级结果，涵盖佐治亚州、密西西比州、新墨西哥州、北达科他州、南达科他州、田纳西州、犹他州、西弗吉尼亚州、科罗拉多州、密苏里州、俄勒冈州、南卡罗来纳州和肯塔基州（13 个州）；另含宾夕法尼亚州和密歇根州的真实选区级结果（并汇总至县级）。 **许可：**数据存储库未公布单独的数据再利用许可；项目的解析器代码库（openelections-core）采用 MIT 许可，基础数据是经县/州选举委员会认证的票数，属于公开选举记录。未发现禁止再利用的条款，因此根据 Pipeworx 针对仅发布批量文件的数据源所制定的规则，本数据包会构建副本并标明许可情况；如果条款未明确说明，也会如实标注。

已知缺口——扩展此数据包前请先阅读

MEDSL 自己的县级和众议院文件受到访问限制，并非只是尚未构建。 MEDSL 的规范数据集“County Presidential Election Returns 2000-2024” 和“U.S. House 1976-2024”（均托管在 Harvard Dataverse 上）都设有 强制访客登记表（姓名、电子邮件、机构和职位均为必填项），且没有记录在案的 API 绕过方式——对这两个数据集的每次文件下载调用，无论匿名还是已通过身份验证的访问，都会返回 "You may not download this file without the required Guestbook response for guestbookID 458"。这是访问限制，并非 robots.txt 问题，因此加载器不会尝试自动绕过（CLAUDE.md 中“身份验证或付费墙”一节适用，即使不会创建持久账户也一样——阻止机器访问的强制身份信息收集表单，本质上属于同一情况）。上文所列 FEC 官方众议院选区文件是无需访问限制的替代方案，适用于 FEC 迄今已发布的选举周期（2020、2022）。如果有人手动填写 MEDSL 访客登记表，并将所得文件交给此数据包，scripts/us-elections/load-data.mjs 可以直接加载——架构已经符合要求（level = 'county'、office = 'HOUSE'）。

FEC 尚未发布汇编版的“Federal Elections 2024”。 截至 2026-10-13 的实时检查结果：fec.gov/.../federal-elections-2024/ 返回 404，且 FEC 自己的年份索引中没有 2024 年（最新的是 2022 年）。这是正常的出版延迟（2022 年版本身也是到 2023 年才汇编完成），并非访问限制——FEC 发布后重新运行加载器即可。FEC 目前已发布的两份 2024 年专属文件无法替代该版本：2024presgeresults.xlsx 仅包含州级总统选举数据，没有政党列；2024congressgecands.xlsx 是众议院／参议院的候选人名录，完全没有得票数。

**县／选区覆盖范围为 15 个州，而非 50 个。**OpenElections 每个州都有独立仓库，且各自使用不同的列布局（这种细分级别没有单一的全国文件）。2026-10-13 使用 gh api 对每个 openelections-data-<st> 仓库的 2024/ 目录进行检查后发现：上文新增的 13 个州（加上最初的 PA/MI/GA）是拥有单个、格式清晰的普选县级或选区 CSV，且符合此加载器列要求的州（county,office,district,party,candidate,votes，可选包含 precinct 列）。未纳入的州包括：其 2024 目录按职位拆分、按县拆分为许多小文件，或完全没有单个普选文件的州：AZ、CT、IN、NH、NJ、NY、RI、TX、WY（已检查）；以及上文未列出的所有 openelections-data-<st> 仓库（未逐一检查——大多数根本没有 2024/ 目录）。添加格式清晰的州很简单（在加载器的 COUNTY_STATES 或 PRECINCT_TO_COUNTY_STATES 中再添加一个条目）；格式较杂乱的州则需要单独进行列映射，就像最初对 PA/MI/GA 调用 oeState() 时所做的那样。

未加载州议会和州长选举数据。任务建议的范围中提到了这些内容；为控制行数和列映射工作量，暂不纳入。FEC 的 2020/2022 选举周期已在全国范围加载美国众议院数据；2024 年仅加载上文所列州的数据（这些州的 OpenElections 州级文件包含相关数据），并非全国范围（MEDSL 的全国众议院文件受上述访问限制，FEC 的 2024 年版尚未发布）。

**尽管原始来源为选区级数据，CO/MO/OR/SC/KY 在此数据包中仅包含县级数据。**这些州的原始联邦职位选区级记录每州约有 2.1 万至 6.4 万行（合计约 21.8 万行）；此处仅存储县级汇总数据（每州少于 2,500 行），以控制加载量和默认响应大小。这是数据量方面的权衡，并非解析能力的限制——如有需要，可扩展 load-data.mjs，像 PA/MI 一样也保留其中 level === 'precinct' 的行。

刷新或扩展数据

重新运行 node scripts/us-elections/load-data.mjs（需要 wrangler 已登录 Pipeworx Cloudflare 账户；如果能看到多个账户，还需设置 CLOUDFLARE_ACCOUNT_ID）——该命令会实时重新获取所有来源，并替换 election_results/sources 表（先删除再重新加载），因为 MEDSL、FEC 和 OpenElections 都会修正历史记录，而非仅追加记录。要添加一个 OpenElections 州，如果其文件符合标准列结构，请在 COUNTY_STATES（文件已细化到县级）或 PRECINCT_TO_COUNTY_STATES（文件为选区级，并会汇总到县级）中添加一项；否则，使用该州自己的列名编写直接的 oeState({...}) 调用（参见 PA/MI/GA 调用，它们展示了目前遇到的两种定制列结构）。

快速开始

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

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

此端点实际提供什么

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

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

也可以连接完整的 Pipeworx 网关，直接列出所有工具包的工具，而不只是当前工具包的工具：

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

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

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

curl -X POST https://gateway.pipeworx.io/v1/tools/election_results \
  -H 'Content-Type: application/json' \
  -d '{"state":"PA","year":2024,"office":"president","level":"county"}'

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

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需经过网关往返：

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

也可以直接运行，确认其能否启动：

npx -y @pipeworx/mcp-us-elections

它通过 stdin/stdout 使用 MCP 通信，并为仅此工具包的工具响应 initialize/tools/list/tools/call——不包含上述网关连接额外提供的共享元工具。数据源相同，工具相同，但没有 ask_pipeworx 路由功能。

使用 ask_pipeworx

除了直接调用工具，你还可以用通俗英语提问——此功能既适用于上述工具包端点，也适用于完整网关：

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

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

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT