FEC MCP 服务器

一个用于联邦选举委员会 (FEC) 竞选财务研究和透明度的模型上下文协议 (MCP) 服务器。该服务器提供用于搜索候选人、检索财务报告以及分析来自官方 FEC 数据的捐款和支出的工具。

功能

• search_candidates: 按姓名搜索联邦候选人，可按选举年份、职位、州或党派进行筛选

• get_committee_finances: 检索财务摘要，包括收入、支出、手头现金和消耗率

• get_receipts: 获取包含捐赠者详细信息的逐项捐款（附表 A）

• get_disbursements: 获取包含收款人和用途详细信息的逐项支出（附表 B）

• Flagged-first notable analysis: 可选的显著性区块，用于显示带有参考列表和启发式标记原因的捐款/支出

• get_independent_expenditures: 追踪超级政治行动委员会 (Super PAC) 支持或反对候选人的支出（附表 E）

• get_committee_flags: 检查 RFAI（额外信息请求）、修正案及相关的合规性红旗警告

• search_donors: 在所有委员会中按姓名、雇主或职业搜索个人捐赠者

• search_spending: 在所有委员会中按描述或收款人搜索竞选支出

所有数据均直接来自官方 OpenFEC API。

安装

先决条件

• Node.js 20 或更高版本

• FEC API 密钥（可从 api.open.fec.gov 免费获取）

从 npm 安装

npm install -g fec-mcp-server

从源码安装

git clone <repository-url>
cd fecmcp
npm install
npm run build

配置

将您的 FEC API 密钥设置为环境变量：

export FEC_API_KEY=your-api-key-here

或者在项目根目录下创建一个 .env 文件：

FEC_API_KEY=your-api-key-here

与 Claude Desktop 一起使用

将服务器添加到您的 Claude Desktop 配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fec": {
      "command": "npx",
      "args": ["fec-mcp-server"],
      "env": {
        "FEC_API_KEY": "your-api-key-here"
      }
    }
  }
}

或者如果已全局安装：

{
  "mcpServers": {
    "fec": {
      "command": "fec-mcp-server",
      "env": {
        "FEC_API_KEY": "your-api-key-here"
      }
    }
  }
}

工具

search_candidates

按姓名搜索 FEC 候选人记录。

参数：

• q (必填): 要搜索的候选人姓名

• election_year (可选): 按选举年份筛选（例如 2024）

• office (可选): 按职位筛选 - H（众议院）、S（参议院）、P（总统）

• state (可选): 按州筛选（2 位字母代码）

• party (可选): 按党派代码筛选（例如 "DEM", "REP"）

示例：

Search for candidates named "Smith" running for Senate in 2024

get_committee_finances

检索竞选委员会的财务摘要。

参数：

• committee_id (必填): FEC 委员会 ID（例如 "C00401224"）

• cycle (可选): 两年选举周期（例如 2024）

返回：

• 总收入和总支出

• 手头现金

• 欠债

• 消耗率（支出/收入比率）

• 捐款明细（个人、PAC、党派）

• 小额捐赠者百分比

示例：

Get the financial summary for committee C00401224

get_receipts

检索委员会收到的逐项捐款（附表 A）。

参数：

• committee_id (必填): FEC 委员会 ID

• min_amount (可选): 最低捐款金额（默认：$1,000）

• two_year_transaction_period (可选): 选举周期（例如 2024）

• cycle (可选): two_year_transaction_period 的别名；自动将捐款与财务周期使用对齐

• contributor_type (可选): "individual"（个人）或 "committee"（委员会）

• include_notable (可选): 包含标记优先的显著性区块（默认：true）

• fuzzy_threshold (可选): 参考列表标记的模糊匹配阈值（默认：90，范围：80-99）

• limit (可选): 结果数量（默认：20，最大：100）

• sort_by (可选): "amount"（金额）或 "date"（日期）（默认："amount"）

示例：

Show the top 10 contributions over $5,000 to committee C00401224

get_disbursements

检索委员会进行的逐项支出（附表 B）。

参数：

• committee_id (必填): FEC 委员会 ID

• min_amount (可选): 最低支出金额（默认：$1,000）

• two_year_transaction_period (可选): 选举周期

• cycle (可选): two_year_transaction_period 的别名；自动将支出与财务周期使用对齐

• purpose (可选): 按用途关键词筛选（例如 "MEDIA", "CONSULTING"）

• include_notable (可选): 包含标记优先的显著性区块（默认：true）

• fuzzy_threshold (可选): 参考列表标记的模糊匹配阈值（默认：90，范围：80-99）

• limit (可选): 结果数量（默认：20，最大：100）

• sort_by (可选): "amount"（金额）或 "date"（日期）（默认："amount"）

示例：

Show media-related spending over $10,000 by committee C00401224

get_independent_expenditures

检索独立支出（附表 E）——即 PAC 和超级 PAC 为支持或反对候选人而花费的资金。

参数：

• candidate_id (可选): FEC 候选人 ID，用于查看针对他们的支出

• committee_id (可选): FEC 委员会 ID，用于查看其独立支出

• support_oppose (可选): 按 "support"（支持）或 "oppose"（反对）筛选

• min_amount (可选): 最低支出金额

• cycle (可选): 两年选举周期

• limit (可选): 结果数量（默认：20）

注意：candidate_id 或 committee_id 必须提供其中之一。

示例：

Show independent expenditures opposing candidate P00009423

get_committee_flags

检查竞选委员会是否存在合规性红旗警告，包括 RFAI 和修正案。

参数：

• committee_id (必填): FEC 委员会 ID

• cycle (可选): 两年选举周期

返回：

• RFAI（额外信息请求）计数和详细信息

• 修正案计数和详细信息

• 近期合规性问题

示例：

Check committee C00401224 for any compliance flags

search_donors

按姓名、雇主或职业在所有 FEC 文件中搜索个人捐赠者。

参数：

• contributor_name (可选): 要搜索的捐赠者姓名

• contributor_employer (可选): 雇主名称（例如 "Goldman Sachs"）

• contributor_occupation (可选): 职业（例如 "Lobbyist"）

• contributor_state (可选): 两位字母的州代码

• min_amount (可选): 最低捐款金额（默认：$200）

• cycle (可选): 两年选举周期

• limit (可选): 结果数量（默认：20）

注意：contributor_name、contributor_employer 或 contributor_occupation 至少需要提供其中之一。

示例：

Find contributions from employees of "Meta" in California

search_spending

按描述或收款人在所有委员会中搜索竞选支出（附表 B）。

参数：

• description (可选): 支出描述中的关键词（例如 "travel", "consulting"）

• recipient_name (可选): 收款人/供应商名称

• recipient_state (可选): 两位字母的州代码

• min_amount (可选): 最低金额（默认：$500）

• cycle (可选): 两年选举周期

• limit (可选): 结果数量（默认：20）

注意：description 或 recipient_name 至少需要提供其中之一。

示例：

Find spending on "golf" or "resort" across all committees

开发

设置

npm install

运行测试

npm test          # Watch mode
npm run test:run  # Single run
npm run test:coverage  # With coverage

构建

npm run build

类型检查

npm run typecheck

实时验收检查

npm run acceptance:fec-day
npm run acceptance:notable

API 速率限制

FEC API 允许使用 API 密钥每小时进行 1,000 次请求。如需更高的限制（每小时最多 7,200 次请求），请联系 FEC。

超时与 API 延迟

默认请求超时为 30 秒。搜索工具（search_candidates、search_donors、search_spending）使用 60 秒超时，因为这些 FEC API 端点执行广泛的数据库扫描，本质上较慢。

要全局覆盖默认超时，请设置 FEC_API_TIMEOUT_MS 环境变量：

export FEC_API_TIMEOUT_MS=45000  # 45 seconds

Docker

在本地构建容器镜像：

docker build -t fec-mcp-server .

在运行时提供您的 API 密钥来运行它：

docker run --rm -i \
  -e FEC_API_KEY=your-api-key-here \
  fec-mcp-server

发布

Glama 检查需要 GitHub 发布。在合并下一次仓库更改后，从 GitHub 创建并发布标签（例如 v1.0.0），或使用以下命令：

git tag v1.0.0
git push origin v1.0.0

许可证

MIT

免责声明

此工具旨在用于竞选财务透明度研究。它以中立、无党派的方式提供对公开 FEC 数据的访问。该工具及其输出不应用于促进或反对任何候选人或政党。

资源

• OpenFEC API 文档

• FEC.gov

• 模型上下文协议

• 参考列表归属：github/DGA-Research/FEC_Coder_Project_Streamlit（捆绑快照位于 resources/reference-lists/ 下）