openfec-mcp-server

---

概览

来自 FEC OpenFEC API 的美国联邦竞选财务数据。搜索候选人、委员会和申报文件，追踪捐款（Schedule A）、支出（Schedule B）、独立和协调政党支出（Schedules E/F），并查询选举竞选、法律文件和申报截止日期。

工具

工具	描述
openfec_search_candidates	按姓名、州、职务、党派或选举周期查找联邦候选人；也可通过 FEC ID 获取单个候选人及其财务总额
openfec_search_committees	按名称、类型、候选人关联情况或州查找政治委员会；也可通过 FEC ID 获取单个委员会
openfec_get_committee_totals	获取单个委员会按选举周期预先汇总的财务总额，或按实体类型对多个委员会进行排名
openfec_search_contributions	获取明细捐款（Schedule A），或按金额、州、雇主或职业汇总
openfec_search_disbursements	获取委员会支出明细（Schedule B），或按用途或收款方汇总
openfec_search_expenditures	获取支持或反对候选人的独立支出（Schedule E），包括明细或按候选人汇总的金额
openfec_search_coordinated_expenditures	获取代表候选人进行的协调政党支出（Schedule F）
openfec_search_filings	按委员会、候选人、表格类型或日期范围查找 FEC 申报文件和报告
openfec_lookup_elections	获取联邦选举中候选人及其筹款总额，或选举汇总
openfec_search_legal	查找咨询意见、执法案件、替代性争议解决、行政罚款和法规
openfec_get_legal_document	获取单份完整法律文件，包括搜索结果中会被删减的数组；文件过大无法在单次响应中返回时，可按条目分页获取
openfec_lookup_calendar	获取 FEC 日历事件、申报截止日期和选举日期

资源

资源	描述
openfec://candidate/{candidate_id}	候选人档案，包含财务总额和主要委员会
openfec://committee/{committee_id}	委员会档案，包含类型、指定类别和财务摘要
openfec://election/{cycle}/{office}	总统选举，包含候选人财务总额
openfec://election/{cycle}/{office}/{state}	参议院或众议院非分区选举，包含候选人财务总额
openfec://election/{cycle}/{office}/{state}/{district}	众议院选区选举，包含候选人财务总额

仅支持工具的客户端也可以通过 openfec_search_candidates、openfec_search_committees 和 openfec_lookup_elections 获取相同数据。

提示词

提示词	描述
openfec_money_trail	追踪候选人相关资金流向：直接筹款、PAC 支持、独立支出和政党支出
openfec_campaign_analysis	对候选人的财务状况进行结构化分析

能力参考

openfec_search_candidates _tool

• query 按姓名搜索，并可按州、选区、职务、党派、选举周期、选举年份、现任者挑战情况、候选人状态和是否已筹集资金筛选；每页最多 100 条；也可通过 candidate_id 查询单条记录（H/S/P + 八个字母或数字），并返回完整记录
• include_totals（按 ID 查询时默认开启）会添加按选举周期划分的 totals 行；当选举周期或选举年份限定总额范围时，每页搜索结果最多包含 35 名候选人；当范围涵盖所有选举周期时，每页最多包含 5 名候选人；未能获取总额的候选人会列在 missing_totals 中
• 类型化错误：candidate_not_found、inputs_not_applicable_to_id_lookup

---

openfec_search_committees _tool

• query 按名称搜索，并可按候选人 ID、州、党派、委员会类型、指定类别、选举周期和财务主管姓名筛选；每页最多 100 条；也可通过 committee_id 查询单条记录（C + 八位数字）
• 类型化错误：committee_not_found、inputs_not_applicable_to_id_lookup

---

openfec_get_committee_totals _工具

• mode: "single"（默认）接收一个 committee_id，并按每个两年周期返回一行；mode: "by_entity_type" 按 entity_type（presidential、pac、party、pac-party、house-senate、ie-only）为所有委员会排名；可按州、类型、指定、组织类型以及收入／支出范围筛选；每页最多 100 条
• 行数据包含收入、支出、现金余额、债务以及明细／非明细拆分；输出中的 mode 表示行数据按周期还是委员会排列
• 类型化错误：committee_id_required_for_single_mode、entity_type_required_for_group_mode、committee_totals_not_found

---

openfec_search_contributions _工具

• itemized（默认）需要 committee_id，并可按捐款人姓名、雇主、职业、城市、州、邮政编码、日期和金额范围以及 is_individual 筛选；每页 30 条；by_size / by_state 接收 committee_id 或 candidate_id，by_employer / by_occupation 接收 committee_id
• 按候选人范围筛选时，输出中的 mode 会变为 by_size_candidate 或 by_state_candidate，且行结构不同；明细响应包含 next_cursor、count 和 count_is_approximate
• 类型化错误：itemized_requires_committee_id、aggregate_requires_committee_id

---

openfec_search_disbursements _工具

• 所有模式均要求 committee_id：itemized（默认；接收方姓名、州、城市和委员会 ID、说明、用途类别、日期和金额范围；每页 30 条）、by_purpose、by_recipient、by_recipient_id
• 明细响应包含 next_cursor、count 和 count_is_approximate；聚合模式按编号分页

---

openfec_search_expenditures _工具

• itemized（默认）可按委员会、候选人、support_oppose、收款人、目标职位／州／选区、政党、is_notice（24/48 小时通知）、日期和金额筛选；most_recent 默认值为 true；按 committee_id 筛选时每页 60 条，否则每页 30 条
• by_candidate 汇总需要 candidate_id 或完整的选举范围（仅 candidate_office=P、S 加 candidate_office_state、H 加州和 candidate_office_district），否则返回 by_candidate_requires_scope

---

openfec_search_coordinated_expenditures _工具

• 可按支出方 committee_id、受益候选人 candidate_id、cycle、收款人、日期和金额设定范围；未设定范围的查询会涵盖所有年份
• 按页分页；按 committee_id 筛选时每页 80 条，否则每页 25 条；行数据包含 subordinate_committee_id，即支出归属的委员会

---

openfec_search_filings _工具

• 筛选条件：committee_id、candidate_id、filer_name、form_type（F3、F3P、F3X、F24、F1、F2、F5）、report_type、report_year、cycle、is_amended 和收件日期范围；每页 65 条
• most_recent 默认值为 true，会隐藏已被替代的修正申报；行数据包含表格类型和报告类型、财务总额以及 pdf_url

---

openfec_lookup_elections _工具

• 必须提供 office 和偶数 cycle；参议院还需要 state，众议院需要 state 和 district，除非使用 zip 限定搜索范围
• mode: "search"（默认）返回该选举中候选人及其总额，以及 candidate_pcc_id / candidate_pcc_name（该周期的主要竞选委员会）；mode: "summary" 返回一条选举汇总行
• 类型化错误：cycle_must_be_even、missing_state_for_office、missing_district_for_house、summary_does_not_support_zip

---

openfec_search_legal _工具

• type（advisory_opinions、murs、adrs、admin_fines、statutes）、query、ao_number、case_number、respondent、citations、penalty bounds 或日期；至少需要提供一项（missing_filter），日期界限还需要提供 type 以及该类型记录的 date_kind
• citations、penalty bounds、respondent、ao_number 和 case_number 各自只适用于部分类型；若与不适用的 type 一起发送，则会以 filter_not_valid_for_type 失败；若省略 type，搜索只会返回这些筛选条件都适用的类型，并统计这些类型的总数。对于 MUR 和 ADR，citation 不能与 case_number、respondent、penalty bound 或开/结案日期界限同时使用，因为上游会忽略这些条件；两个 citation 字段同时提供时，将匹配其中任意一个
• citation 须采用上游可解析的形式——52 U.S.C. 30104 或 11 CFR 110.1（USC、C.F.R.、§ 和 30104(g) 这类后缀均可）；单独的 30106 或 110.1 会以 invalid_citation 失败，而不会静默返回未筛选的结果。每个字段只能提供一个 citation：上游只会应用值中的第一个 citation，因此 52 U.S.C. 30104, 52 U.S.C. 30118 也会以同样的方式失败
• 通过 from_hit / hits_returned 进行偏移分页；每种类型最多 200 条，且位于 10,000 条结果的窗口内
• 结果会经过精简：documents 替换为 document_count 和 document_categories，dispositions 替换为 disposition_count 和 disposition_categories，highlights 最多保留 3 条，移除其中的 <em> 匹配标记并逐行显示；commission_votes 则缩减为日期和不超过 200 个字符的操作说明；openfec_get_legal_document 会返回完整记录
• 每个响应都不超过 100,000 字节：结果按类型逐一完整纳入，直到下一个类型无法容纳；若页面未能容纳部分结果，则会报告 truncated、shown 和 nextFromHit——即每种类型的后续 from_hit，与该 type 一起传回

---

openfec_get_legal_document _工具

• doc_type 是某条搜索结果的 document_type 的复数形式（mur → murs）；no 是该结果的 no 字段
• 返回未经精简的记录，包括 documents、commission_votes 和 dispositions；找不到时会以 legal_document_not_found 失败
• 若记录超过 100,000 字节，则返回其标量字段、能容纳的数组（从最小的开始），以及 withheld——其中列出每个暂不返回的数组及其条目数和大小；对于仍能容纳的数组条目，可使用 array 和 offset 重新调用，并获取 next_offset。若记录中不存在该数组，则会以 array_not_in_record 失败

---

openfec_lookup_calendar _工具

• events（默认；category，18 个代码之一，以及 description）、filing_deadlines（report_type、report_year）或 election_dates（state、office、district、election_year）；所有模式均可使用 min_date / max_date，每页最多 100 条
• district 筛选条件永远不会匹配无分区选区；请将其与 state 配合使用

---

openfec://candidate/{candidate_id} _资源

• 候选人记录与其财务总额及 principal_committees 合并（当前 designation 为 P，不限定选举周期）
• candidate_id 来自 openfec_search_candidates；找不到时会以 candidate_not_found 失败

---

openfec://committee/{committee_id} _资源

• 委员会记录与其财务总额合并；未提交 Form 3/3X/3P 的委员会没有财务总额
• committee_id 来自 openfec_search_committees；找不到时会以 committee_not_found 失败

---

openfec://election/{cycle}/{office} _资源

• 总统选举（office 为 P），包含整个选举期间的总额
• 仅提供第一页：持续较长的选举会显示指向 openfec_lookup_elections 的 truncation_notice，没有结果时则显示 empty_result_notice

---

openfec://election/{cycle}/{office}/{state} _资源

• 参议院选举，或单一选区州的无分区众议院选举（office 为 S 或 H）
• 与总统选举模板一样，仅提供第一页，并显示相同的提示

---

openfec://election/{cycle}/{office}/{state}/{district} _资源

• 众议院选区选举（office H）
• 首页面限制和提示与总统选举模板相同

---

openfec_money_trail _提示词

• 参数：candidate_name 或 candidate_id（必填其一），cycle 可选
• 七个步骤：识别候选人，通过 candidate_pcc_id 确定该周期的主要委员会，然后依次查看直接筹款、独立支出、协调的政党支出、支出情况，最后进行综合分析

---

openfec_campaign_analysis _提示词

• 参数：candidate_name 或 candidate_id（必填其一），cycle 可选
• 七个步骤：候选人概览、主要委员会及各周期走势、筹款构成、资金消耗率、竞争态势、外部资金，以及评估

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔的身份验证（none / jwt / oauth）、可切换的存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

OpenFEC 专属功能：

• 为 OpenFEC REST API 提供类型安全的客户端，支持重试和可配置的超时；错误消息会移除 API 密钥，HTTP 故障会附带恢复提示
• 周期为覆盖两个日历年的偶数年份（2024 = 2023 年 1 月 – 2024 年 12 月）；未提供 cycle 时，明细 Schedule A/B/E 默认使用当前周期；election_full（默认为 true）会将选举总额扩展至完整选举周期（总统 4 年、参议员 6 年、众议员 2 年）
• 明细捐款和支出需按 committee_id 查询，而非 candidate_id。委员会的 designation 和 principal_committees 仅反映当前指定情况，因此要查询某个周期的主要委员会，请从 openfec_lookup_elections 读取 candidate_pcc_id
• 明细 Schedule A/B/E 使用不透明的 next_cursor 翻页，该游标仅对其他参数完全相同的调用有效；其他工具按页码翻页，法律搜索按偏移量翻页

便于 Agent 使用的输出：

• 回显生效查询：每个工具响应都包含应用默认值后的筛选条件 search_criteria；没有结果时会附带说明如何放宽筛选条件的 notice
• 每种输出形式的响应上限为 100,000 字节：高流量工具会限制每页行数；当页面结果少于请求的 per_page 时，会报告 truncated、shown 和 cap（基于页码的工具还会在 pagination.per_page 中回显实际应用的页面大小）；法律搜索会暂不返回完整结果，并报告 nextFromHit；大型法律文档会按 offset 对数组分页；仅查询一个委员会时，会将该委员会提升至顶层的 committee 字段，而不是在每行重复显示
• 类型化契约：多模式工具会回显解析后的 mode，并拒绝该模式无法应用的筛选条件（itemized_only_filters_in_aggregate_mode、inputs_not_applicable_to_mode），而非直接忽略；每次失败都会附带类型化的 reason 和 recovery 文本；估算总数会标记为 count_is_approximate

开始使用

公共托管实例

可使用公共实例 https://openfec.caseyjhand.com/mcp，无需安装。该实例提供 Streamable HTTP；每个客户端的配置格式各不相同。

Claude Code：

claude mcp add --transport http openfec-mcp-server https://openfec.caseyjhand.com/mcp

Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "openfec-mcp-server": {
      "type": "streamableHttp",
      "url": "https://openfec.caseyjhand.com/mcp"
    }
  }
}

Cursor（mcp.json）：

{
  "mcpServers": {
    "openfec-mcp-server": {
      "url": "https://openfec.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在“设置”→“连接器”中添加远程服务。

自托管 / 本地使用

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "openfec-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/openfec-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "FEC_API_KEY": "your-api-key"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "openfec-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/openfec-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "FEC_API_KEY": "your-api-key"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "openfec-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "FEC_API_KEY=your-api-key", "ghcr.io/cyanheads/openfec-mcp-server:latest"]
    }
  }
}

使用 Streamable HTTP 时，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 FEC_API_KEY=your-key bun run start:http
# Server listens at http://localhost:3010/mcp

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 可选：免费的 OpenFEC API 密钥 可将速率限制从默认 DEMO_KEY 的每小时 30 次请求提高到每小时 1,000 次。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/openfec-mcp-server.git

2. 进入目录：

cd openfec-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set FEC_API_KEY (optional)

配置

变量	描述	默认值
FEC_API_KEY	来自 api.data.gov 的 OpenFEC API 密钥。DEMO_KEY 每小时允许 30 次请求；自有密钥允许 1,000 次。	DEMO_KEY
FEC_BASE_URL	OpenFEC API 基础 URL。	https://api.open.fec.gov/v1
FEC_MAX_RETRIES	API 请求失败时的重试次数。	3
FEC_REQUEST_TIMEOUT	单次请求超时时间，单位为毫秒。	30000
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。覆盖服务声明的 stateless 模式。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  bun run rebuild
  bun run start:stdio   # or start:http
  

• 运行检查和测试：

  bun run devcheck      # Lint, format, typecheck, security audit
  bun run test          # Vitest test suite
  bun run lint:mcp      # Validate MCP definitions against spec
  

Docker

docker build -t openfec-mcp-server .
docker run --rm -e FEC_API_KEY=your-key -p 3010:3010 openfec-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/openfec-mcp-server。默认会安装 OpenTelemetry 对等依赖；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口——注册工具、资源和提示词，并初始化 OpenFEC 服务。
src/config	使用 Zod 解析并验证服务专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts），共享验证器和格式化器位于 definitions/utils/。
src/mcp-server/resources	资源定义（*.resource.ts）。包含候选人、委员会和三种选举竞选模板。
src/mcp-server/prompts	提示词定义（*.prompt.ts）。用于资金流向和竞选分析。
src/services/openfec	OpenFEC API 客户端和领域类型。
tests/	单元测试和集成测试，结构与 src/ 对应。
scripts/	构建、清理、devcheck、tree、changelog 和 lint 脚本。
docs/	设计说明和 OpenFEC OpenAPI 规范。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明如下：

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 src/mcp-server/*/definitions/index.ts 的导出入口中注册新工具和资源
• 封装 OpenFEC API：验证原始数据 → 规范化为领域类型 → 返回输出模式；绝不伪造上游响应中未提供的字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。