Form4API MCP — SEC Form 4 Insider Trading

form4api-mcp

为任何兼容 MCP 的 AI 助手提供生产级 SEC Form 4 内幕交易数据——支持修正文件识别、清晰区分 10b5-1 交易，并叠加 Form 144 + 机构 13F-HR 数据，以及国会 STOCK Act 交易和内幕人士/国会议员交易汇合分析——39 个工具 + 6 个现成研究提示词

一个 MCP 服务，可将托管的 Form4API REST API 提供给 Claude Desktop、Cursor、Windsurf、VS Code、Codex CLI 及其他任何兼容 MCP 的客户端。只需配置一次，大模型便可在研究过程中直接回答有关内幕交易、机构持仓和出售意向申报的问题。

基于抓取的替代方案无法做到的四项数据质量保证：

• 🛡 支持修正文件识别 — 自动协调 Form 4/A 修正文件。内幕人士更正申报时，不会重复计数。
• 🎯 清晰区分 10b5-1 交易 — 每笔交易都会标记为预先安排（10b5-1 计划）或自主决定。聚类信号从设计上排除计划交易。
• 📜 Form 144 出售意向 — 已索引 125K+ 份 Form 144 申报。在内幕人士出售行为出现在 Form 4 中约 2 天前发现它们。
• 🏛 机构 × 内幕人士联查 — 每笔交易都会在同一响应中附带当前 13F-HR 持股背景（前三大持有人、AUM 趋势）：无需二次调用，也无需在客户端联查。在我们调查过的自助式 SEC 数据 API 中，没有一家能通过单次查询同时返回两类数据——sec-api.io 和 Kaleidoscope 都将 13F 和内幕交易数据作为独立端点提供。

---

快速安装

1. 获取免费 API 密钥

前往 www.form4api.com → 登录 → 控制面板。免费计划每天包含 500 次请求，无需信用卡。

2. 添加到 MCP 客户端

Claude Desktop — 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "form4api": {
      "command": "npx",
      "args": ["-y", "form4api-mcp"],
      "env": {
        "FORM4API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

重启客户端。工具会自动显示。

Claude Code（CLI）：

claude mcp add form4api -- npx -y form4api-mcp

…然后在 shell 或 ~/.claude/mcp.json 中设置 FORM4API_KEY。

Cursor — 编辑 ~/.cursor/mcp.json（用户级）或 .cursor/mcp.json（工作区级）：

{
  "mcpServers": {
    "form4api": {
      "command": "npx",
      "args": ["-y", "form4api-mcp"],
      "env": {
        "FORM4API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

重启 Cursor。工具会自动显示。

Windsurf — 编辑 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "form4api": {
      "command": "npx",
      "args": ["-y", "form4api-mcp"],
      "env": {
        "FORM4API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

重启 Windsurf。工具会自动显示。

VS Code — 编辑 .vscode/mcp.json（工作区级）。注意：VS Code 使用 servers 键（而非 mcpServers）：

{
  "servers": {
    "form4api": {
      "command": "npx",
      "args": ["-y", "form4api-mcp"],
      "env": {
        "FORM4API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

重启 VS Code。工具会自动显示。

Codex CLI — 配置文件采用 TOML 格式，位于 ~/.codex/config.toml：

[mcp_servers.form4api]
command = "npx"
args = ["-y", "form4api-mcp"]
env = { FORM4API_KEY = "YOUR_API_KEY" }

验证是否正常工作

让大模型运行 verify_setup 工具——它会确认 API 密钥有效且 MCP 服务可访问；否则会返回确切的修复步骤。

示例：“运行 verify_setup 工具，确认 MCP 已正确配置。”

提交密钥前先试用

get_public_stats 是一个无需密钥的工具——即使未设置 FORM4API_KEY 也能使用。先试用它，在注册前预览实时数据覆盖范围：

FORM4API_KEY="" npx form4api-mcp

确认效果符合预期后，前往 www.form4api.com 注册并获取免费密钥 → 设置 FORM4API_KEY → 解锁所有工具。

3. 或直接运行

FORM4API_KEY=YOUR_API_KEY npx form4api-mcp

---

可用工具（39 个）

搜索

工具	描述	计划
search	将公司名称、部分股票代码或个人姓名解析为股票代码或 CIK——当你还没有标识符时，通常首先调用此工具。返回分别排序的 companies 和 insiders 列表	免费

Form 4 内幕交易

工具	描述	计划
research_company	单次调用即可获取某个股票代码的综合内幕研究背景信息——公司简介、近期交易、集群信号、情绪，以及计算得出的买入／卖出方向总结。当某个部分需要更高级别计划时，会优雅降级，取代 4 次单独调用	免费（信号／情绪部分需要 Business）
get_transactions	搜索内幕交易——可按股票代码、内幕人士、日期范围、交易代码或整个类别筛选（exclude_category=derivatives）、筛选 10b5-1 计划交易、设置金额下限（min_value）、内幕人士的角色（role：高管、董事或持股 10% 的所有者），按交易规模排序（sort=value；默认按时间从新到旧），查看 13F 持仓趋势（inst_ownership_trend），或使用 significant=true 仅查看真正自主决定的买入／卖出。Pro 还支持其余交易规模筛选条件（max_value、min_shares、max_shares）和交易后回报筛选（min_return_1d…max_return_6m、has_returns；回报以小数表示，0.05 = +5%）。分页深度受计划限制——请参阅 Plans	免费
get_recent_filings	最新 Form 4 申报文件，可选择按股票代码筛选	免费
list_filings	Form 4 申报文件的分页列表，按申报时间从新到旧排列——可按股票代码、cik 或申报日期范围筛选。使用此工具翻页浏览申报文件；get_recent_filings 返回的是同一数据流中未经筛选的最新部分	免费
get_filing	按 accession number 查询单份申报文件	免费
get_insider_profile	内幕人士简介——姓名、职务，以及董事／高管／持股 10% 所有者标记	免费
get_insider_transactions	某位特定内幕人士（按 CIK 查询）的所有交易	免费
get_company_overview	公司简介——名称、CIK、SIC 行业、州、网站、申报文件数量	免费
get_company_insiders	为某家公司提交过 Form 4 的所有内幕人士	免费
get_company_peers	同一 SIC 行业的相似公司（优先使用 4 位行业代码，再根据 2 位前缀补充），按过去 12 个月的 Form 4 申报数量排序	免费
list_companies	公司列表，按名称或申报文件数量排序	免费
get_insider_directory	按姓氏字母顺序浏览内幕人士——提供 A-Z 字母索引和每个字母对应的人数，以及所选字母下的一页内幕人士	免费
get_insider_career_summary	职业生涯汇总数据：买入／卖出总额、主要公司、10b5-1 交易占比、平均回报	Pro
get_insider_scorecard	内幕人士（CIK）的买入记录评分卡——自主公开市场买入的命中率及平均／中位回报；成熟样本少于 5 笔时返回 null	Pro
get_insider_leaderboard	按 hit_rate 或 avg_return 排名的顶级内幕人士；可按 horizon（3m/6m）、min_trades 和 limit 筛选	Business

信号 + 情绪

工具	描述	计划
get_signals	买入／卖出集群信号——同一家公司有多位内幕人士做出方向相同的交易。自动排除 10b5-1 交易	Business
get_sentiment	每个股票代码的 MSPR 风格月度情绪评分（-100 至 +100）。排除 10b5-1 交易，使评分反映内幕人士的真实信念	Business

Form 144 + 机构持仓

工具	描述	计划
get_form144	拟议出售通知申报文件——在 Form 4 出售申报文件出现前约 2 天提供早期信号	Business
get_holdings	Form 13F-HR 机构持仓（可按股票代码、CUSIP、管理机构、季度、最低价值筛选）	Business
get_managers	机构管理机构索引，包含最新 AUM	Business
explain_signal	说明信号触发原因——计入统计的内幕人士与交易、排除项及判定标准	Business
get_data_quality	公开数据质量、时效性和覆盖范围指标	免费
list_schedule13_dg	某家公司的 Schedule 13D/13G 超过 5% 实益所有权变动——申报人、持股比例、事件日期、表格类型	Business

国会 + 汇聚

工具	描述	方案
list_congress_trades	国会 STOCK Act 交易（定期交易报告）——可按股票代码、政治人物、党派、院、州、交易类型、最低金额或日期范围筛选。仅覆盖美国众议院——参议院 eFD 会阻止数据中心流量，因此 chamber=Senate 不会匹配任何结果，响应中会附带 X-Coverage-Note: chamber-not-covered。每条记录都包含 amountLow/amountHigh（披露的金额区间，绝不伪造中间值）和 disclosureLagDays——根据 STOCK Act，披露最多可延迟 45 天，因此这里的“实时”是指披露后几分钟，而不是交易后几分钟	免费（30 天披露窗口；Starter 为 366 天；Pro+ 为无限历史记录）
list_congress_politicians	按国会交易活动对政治人物进行排名汇总——交易总数、买入/卖出数量以及最近披露信息	Pro
get_congress_politician	根据 bioguide ID 获取某位政治人物的完整档案——交易总数、交易最多的股票代码以及最近交易	Pro
get_congress_ticker_rollup	查询交易过某个股票代码的政治人物，以及净买入/卖出数量	Pro
get_convergence_signals	查询内幕人士集群买入与国会购买在滚动时间窗口内发生的股票代码。strength 是有文档说明的算术计算（不同的国会买入者数量 × 该信号中的内幕人士数量）——绝非黑箱或预测评分。不计算或暗示任何绩效/阿尔法收益	Pro

实用工具

工具	描述	方案
check_usage	你的 API 密钥使用统计和当前方案	免费
get_key_activity	此密钥近期的 API 请求	免费
get_usage_history	过去 N 天的每日请求数	免费
search_insiders	按内幕人士姓名进行子字符串搜索	免费
list_webhooks	列出你的 webhook 订阅，并显示每个 webhook 的投递状态（lastAttemptAt、lastSuccessAt、lastStatusCode、lastErrorClass）和自动禁用状态。只读	免费
get_webhook_events	重放自某个时间戳以来的 webhook 投递事件。只读	免费
verify_setup	验证 MCP 配置是否正确——确认 API 密钥有效且服务可访问	免费
get_public_stats	整个公共语料库的总量统计（申报、交易、公司、13F-HR AUM、数据摄取延迟）——无需 API 密钥	免费（无需密钥）
get_status_history	公共状态页过去 90 天的每日运行时间历史记录	免费（无需密钥）
health_ingestion	实时数据摄取健康检查——Form 4 新鲜度、解析队列积压、价格数据流延迟	免费（无需密钥）

---

提示词（6 个）

除了 39 个工具外，这个 MCP 还提供 6 个提示词——现成的研究方案，客户端可以列出（prompts/list）并加载（prompts/get），这样你就不必手动拼装合适的工具调用顺序。每个提示词都会明确告知大模型应调用哪些 SEC Form 4 / Form 144 / 13F-HR 工具、调用顺序，以及如何解读受计划限制的结果。

提示词	参数	功能
insider_monitor	ticker	查询某只股票近期的 SEC Form 4 内部人活动——交易（标记 10b5-1）、集群信号、情绪——并结合交易后收益背景，总结买入／卖出的信心
cluster_buy_scan	days（默认值为 7）	扫描全市场近期的集群买入信号，排除 10b5-1，按信心（内部人人数 + 金额）排序，并为每项提供情绪评分
form144_early_warning	ticker（可选）	将待执行的 Form 144 拟议出售通知申报与近期 Form 4 卖出交叉核对——将自由裁量（非 10b5-1）通知标记为信号最强的预警，约可提前 2 天发现出售
exec_conviction_check	insider（姓名或 CIK）	查询某位内部人的职业记录——买入／卖出总量、历史自由裁量买入的交易后收益，以及其买入历来是否跑赢预定的 10b5-1 卖出
institutional_insider_overlap	ticker	将 13F-HR 机构持仓与近期内部人交易结合起来，找出聪明资金与内部人观点一致或分歧之处
post_selloff_buys	min_return（默认值为 0.05）	使用交易后收益筛选条件筛查内部人买入，找出历史上成功的逢低买入模式

这些提示词对应的是基于方案的工作流，而基于抓取的 Form 4 MCP 无法提供这些工作流——每个提示词都依赖只有此 MCP 才能提供的数据（10b5-1 标记、Form 144、13F-HR 联合数据、按内部人评估收益）。我们会如实遵守方案要求：涉及 Business 方案工具（get_signals、get_sentiment、get_form144、get_holdings、get_managers）或 Pro 方案工具（get_insider_career_summary、get_insider_scorecard）的提示词，会指示大模型展示结构化的 upgrade_required 响应，而不是静默失败。

在 Claude Desktop 中，提示词会显示为 / 斜杠命令选择器；在 Claude Code 或其他 MCP 客户端中，要求助手“使用 insider_monitor 提示词查询 NVDA”（或类似请求），它就会获取并遵循该方案。

---

示例提示词

已配置？可以向大模型提问：

以质量为先（需要我们的修订感知、排除 10b5-1 并经过关联的数据集）：

• “显示本周的集群买入信号——仅限自由裁量交易，不包括计划交易”
• “本季度哪些公司的内部人在买入，同时机构持股比例也在增加？”
• “NVDA 是否有任何 Form 144 申报显示即将出售？”
• “排除 10b5-1 计划后，TSLA 过去 6 个月的月度内部人情绪如何？”
• “Berkshire Hathaway 持有的主要 13F-HR 持仓有哪些？本季度增持或减持了什么？”

常规内部人研究：

• “过去 30 天 NVDA 有哪些内部人交易？排除 10b5-1 计划”
• “Tim Cook 的职业内部人交易概况是什么？”
• “列出 Tesla 在 2026 年所有超过 100 万美元的公开市场买入”
• “Microsoft 的 CFO 今年如何处理其持股？”

---

为什么选择此 MCP，而非基于抓取的替代方案

该领域的一些 MCP 会抓取免费的公共网站（例如 openinsider.com）来获取 Form 4 数据。这对于快速原型来说没问题，但它们提供给大模型的数据层存在一些结构性缺陷：

	form4api-mcp	基于抓取的 MCP
Form 4/A 修正文件处理	✅ 自动核对	❌ 重复计数
10b5-1 计划标记	✅ 每笔交易均有标注	❌ 计划交易与自主交易混在一起
Form 144 出售意向	✅ 125K+ 份申报	❌ 未提供
机构投资者与内部人士联合查询	✅ 每笔交易均包含前三大持有人及 AUM 趋势	❌ 仅包含内部人士
情绪（不含 10b5-1）	✅ 类 MSPR 评分	❌ 计划交易会污染评分
数据源稳定性	✅ 托管 API 合约	❌ 数据源 HTML 变更时会失效
Webhook／生产环境交付	✅ HMAC + 重试 + DLQ	❌ 仅支持 MCP，无备用方案
SDK	✅ Python + JS	❌ 仅支持 MCP
商业支持	✅	❌

如果你的大模型会话是一个真实研究工作流的起点，而该工作流最终需要生产环境交付，那么选择一个支持后续升级的 MCP 很重要。

---

超越 MCP——满足更多需求

Webhook 工具仅供读取。 MCP 可以列出你的 webhook（list_webhooks）并重放交付事件（get_webhook_events），除此之外不能执行其他操作。创建、删除、启用和测试 webhook，以及设置自定义身份验证标头，都需要通过 REST API 或控制台完成。这是有意为之：MCP 不提供任何用于写入 webhook 的工具。

MCP 是最简单的入门方式。当你的工作流超越大模型中介的研究场景后，Form4API 平台的其他功能也近在咫尺：

• Webhooks — HMAC 签名、指数退避、死信队列、持续失败时自动禁用。适用于生产环境流水线，而不仅是大模型聊天。
• Python SDK — pip install form4api（PyPI）
• JS / TypeScript SDK — npm install form4api（npm）
• 控制台 — 用量、自助计费、密钥轮换、Webhook 健康状态、账单历史。

MCP 与上述所有功能使用相同的后端——大模型引用的每一条事实，都可以通过这些渠道中的任意一种，使用同一个密钥以编程方式重新获取。

---

方案

39 个工具中有 25 个可在免费方案中使用，而且今天免费的工具今后也会一直免费。 新增高级功能将在推出时分级提供；你当前密钥已经可以使用的功能，之后不会被收回。

工具	免费	Pro	Business
search	✓	✓	✓
get_transactions、get_recent_filings、get_filing	✓	✓	✓
get_insider_profile、get_insider_transactions	✓	✓	✓
get_company_overview、get_company_insiders、get_company_peers	✓	✓	✓
get_insider_career_summary、get_insider_scorecard	—	✓	✓
get_insider_leaderboard、get_signals、get_sentiment	—	—	✓
get_form144、get_holdings、get_managers	—	—	✓
explain_signal、list_schedule13_dg	—	—	✓
list_congress_trades	✓（30 天披露窗口）	✓（不限历史记录）	✓（不限历史记录）
list_congress_politicians、get_congress_politician、get_congress_ticker_rollup、get_convergence_signals	—	✓	✓
每日请求数	500	50,000	250,000
每分钟请求数	60	200	500
get_transactions 分页深度	20 页	不限	不限

Starter 介于 Free 和 Pro 之间：每天 7,500 次、每分钟 120 次请求，get_transactions 分页深度为 100 页，国会交易历史窗口为 366 天。表格中标为 Pro 或 Business 的工具仍需要相应方案。Enterprise 每天请求数不限，每分钟最多 2,000 次。

对于大批量历史数据提取，请使用 REST /v1/transactions/export 端点（Business），而不要分页——它会通过一次请求将整个筛选结果集以 CSV 格式流式传输。

Agent 在付费墙前看到的内容

受限调用不会只返回一个裸 HTTP 错误。MCP 会返回结构化的 upgrade_required 负载，让模型能在一次回复中说明情况和解决方法：

{
  "error": "upgrade_required",
  "required_plan": "business",
  "current_plan": "Free",
  "message": "This endpoint requires the Business plan or higher. Your current plan is Free.",
  "unlocks": "The Business plan includes cluster-buy signals and sentiment scores, 13F institutional holdings and managers, Form 144 notices, bulk CSV export, and 250,000 requests/day."
}

message 是 API 自身的说明，会原样保留——其中指出了阻止调用的具体限制或参数，这通常正是模型提出可行替代方案所需的信息。对免费工具使用仅限 Pro 的参数时，也会返回相同格式，因此模型只需去掉该筛选条件后重试即可。

仅当 API 提供 upgrade_url 时才会包含该字段；否则会省略。

---

数据覆盖范围

• 来自 SEC EDGAR 的 138 万+ 份 Form 4 交易
• 所有申报公司的 62 万+ 份申报文件
• 12.5 万+ 份 Form 144 拟议出售通知申报文件（Business+）
• 超过 118,000 份申报文件中的 4,500 万+ 条 Form 13F-HR 持仓记录，最新完整季度的管理资产规模超过 80 万亿美元（Business+）
• 超过 3.3 年的历史数据（自 2023-04 起）
• 每笔交易均标记 10b5-1 计划
• 识别修订申报——已核对 Form 4/A
• 国会议员 STOCK Act 交易——仅包含美国众议院书记官定期交易报告（不摄入参议院 eFD 数据）。所有套餐均可使用 list_congress_trades，历史数据窗口因套餐而异（Free 为 30 天，Starter 为 366 天，Pro+ 不限）；政客汇总和趋同分析需要 Pro+。提供数字化申报；金额始终按披露的范围显示（amountLow/amountHigh），绝不编造中间值；每笔交易还会提供 disclosureLagDays（根据 STOCK Act，最长为 45 天）
• 实时摄入——SEC 发布新申报文件后数分钟内即可获取

---

安装为 Claude Desktop Extension（DXT）

仓库根目录中包含一个 manifest.json，可通过 Desktop Extensions (DXT) 格式一键安装。Claude Desktop 原生支持 .dxt 文件后，可使用以下命令打包并安装：

npx @anthropic-ai/dxt pack
# Produces form4api-mcp.dxt — open it in Claude Desktop to install

在此之前，请使用上文“快速安装”中所述的标准 claude_desktop_config.json 方法。

---

工具如何与后端保持同步

此 MCP 分为两层：

• src/tools/*.ts 中的手写工具（交易、信号、情绪、form144、持仓等）——这些工具带有面向大模型的区分性描述（识别修订申报、准确处理 10b5-1 等），让此 MCP 能在备选方案中被正确选中。
• src/tools/_generated.ts 中的自动生成工具——由 npm run codegen 从 https://api.form4api.com/openapi/v1.json 生成。每个新增到 OpenAPI 规范中的后端端点都会自动加入此文件。CI 会在每个 PR 上运行 npm run codegen:check；如果已提交文件与实时规范生成的结果不一致，就会导致构建失败，因此 MCP 绝不会在不知情的情况下落后于后端。

添加新的生成工具：在后端发布端点，重新生成（npm run codegen），提交 src/tools/_generated.ts，然后发布。无需编写工具封装代码。

这 6 个配方提示词位于 src/prompts/recipes.ts 中——同样是手写的，并非自动生成。它们不会增加任何后端功能；每个提示词都是客户端模板，用来告诉大模型应调用哪些现有工具，以及调用顺序。

---

链接

• Form4API — API 主页
• 文档 — 完整的 REST API 参考
• 控制面板 — 管理 API 密钥、查看用量、配置 Webhook
• 状态 — 实时运行时间、数据库和摄入队列的运行状况
• npm — npm 包
• mcp.so — MCP 服务目录条目