奇链 奇链
← 教程库
入门 约 20 分钟 2026-10-22 01:25:33 · 24 阅读

EdgarTools MCP 接入实操：让 AI 直查 SEC 申报的 13 个工具

SEC 的 EDGAR 系统免费公开 1994 年以来的全部申报文件——10-K 年报、8-K 重大事项、13F 机构持仓、内部人交易 Form 4，什么都有，但原始数据几乎不可直接用。EdgarTools 这个 MIT 开源的 Python 库（GitHub 2800+ star）把这些文件解析成带类型的数据对象，官方还配了一个 MCP 服务器：接进 Claude Code 或 Claude Desktop，直接问「英伟达最新年报的风险因素说了什么」「伯克利最近一个季度增持了哪些股票」，AI 会自己去查。这篇从安装到真实查询走一遍全流程，附实测记录。

准备：一台 Python 3.11+ 的机器，加一个邮箱

没有 API Key，没有注册，没有费率档位。SEC 对自动化工具的唯一要求是自报身份，官方文档原话：

EDGAR requires a contact email on every request. There is no key, signup or rate-limit tier.

—— edgartools 官方文档 Quick Start

身份通过环境变量 EDGAR_IDENTITY 传，格式是「名字 + 空格 + 邮箱」。限制方面：SEC 公平访问上限 10 请求/秒（库自身遵守），全文搜索覆盖 2001 年以来的申报，库要求 Python 3.11+（PyPI 页写 ≥3.10，以官方文档为准）。

三种客户端，三种接法

三种客户端接入方式对照

Claude Code 一行命令、Claude Desktop 配置文件、免装 uvx 变体，以及 EDGAR_IDENTITY 的格式

Claude Code 最简单，一行注册：

claude mcp add edgartools -- uvx --from "edgartools[ai]" edgartools-mcp
export EDGAR_IDENTITY="你的名字 your@email.com"

Claude Desktop 是子进程方式，有个官方文档专门强调的坑：Desktop 只继承极简 PATH（/usr/local/bin、/usr/bin、/bin），Homebrew/pyenv/conda 装的 Python 它找不到，配置里必须写 which python3 查出来的绝对路径，否则报 spawn python3 ENOENT：

{
  "mcpServers": {
    "edgartools": {
      "command": "/usr/local/bin/python3",
      "args": ["-m", "edgar.ai"],
      "env": { "EDGAR_IDENTITY": "你的名字 your@email.com" }
    }
  }
}

注意 args 里的模块路径是 edgar.ai（包内部结构），而命令行入口名是 edgartools-mcp——实测直接跑 python -m edgar.ai.mcp 会报 No module named edgar.ai.mcp.__main__，按文档用 edgartools-mcp 或 python -m edgar.ai 就对。装完先跑健康检查：

pip install "edgartools[ai]"
python3 -m edgar.ai --test

13 个工具：发现、检视、分析

13 工具分组图

13 个工具按意图分三组：发现 5 个、检视 4 个、分析 4 个，工具名与数量经 stdio 实测核对

官方 Tools Reference 页特意说明工具是「按你想做什么组织，而不是按 API 结构组织」。三组的分工：edgar_company 是多数问题的起点，一次返回公司画像、财务、近期申报与股权；拿到申报后用 edgar_read 抽具体章节（10-K 的 risk_factors、mda 等）；要跨公司看就用 edgar_compare 与 edgar_trends。官方文档还给了四条常用链路：

Company research: edgar_company → edgar_read (10-K sections) → edgar_trends
Filing analysis: edgar_filing (by accession or URL) → edgar_read (extract sections)
Event monitoring: edgar_monitor → edgar_filing (examine new filings)
Peer comparison: edgar_screen (find peers) → edgar_compare (compare metrics)

—— 官方文档 Common Workflows 一节

实测：从健康检查到真实数据

实测三连

健康检查 13 tools registered、edgar_company 查英伟达的真实返回、参数名传错的校验报错

在 Linux + Python 3.11 虚拟环境（uv venv + uv pip install edgartools[ai]，装好约 379 MB、139 个包）实测 stdio 全链路。健康检查输出与官方文档示例逐行同构，版本为 v5.62.0（文档示例截图还是 v5.26.1，这是滚动更新的库，以自己装的为准）。

问英伟达，edgar_company 传 identifier: "NVDA"（ticker、CIK、公司名都往这个参数传），返回里公司画像字段很全，摘几条真实值：

"company": "NVIDIA CORP", "cik": "1045810"
"industry": "Semiconductors & Related Devices"
"exchanges": ["Nasdaq"], "filer_status": "Large accelerated filer"
"shares_outstanding": 24100000000.0, "public_float": 4000000000000.0

参数名传错时校验很干脆——传 ticker 得到 Input validation error: 'identifier' is a required property，报错里直接点名正确参数。

全文搜索实测撞到一个值得记的行为：用 edgar_text_search 搜 "tariff"、限定 forms: ["10-K"] 并指定 start_date: "2025-01-01"，返回 total_matches: 10000，可抽出来的头三条却是 2002、2003、2010 年的老 10-K。返回体的 date_range 字段显示过滤条件带上了，但结果排序明显相关度优先、老文件靠前。要严格时间序的结果，把 limit 拉大翻页，或者换 edgar_search 按元数据过滤更稳。

本地库与托管版对比

本地 edgartools（免费直连 SEC）与 edgar.tools 托管版（$24.99/月 AI 增强）的分工，附日期过滤实测教训

本地库还是托管版

官方把这事说得很直白：本地库免费、MIT、跑在你自己进程里，数据原始可复现；edgar.tools 托管平台收费（免费档返回截断，Professional 全量 24.99 美元/月），卖点是服务端 AI 增强——8-K 事件自动分类、12 个 XBRL 主题簇检索、80 万+ 内部人交易带情绪标注。官方原话是「你不是在为解析付费，是在为有人替你跑着并回答问题付费」。做研究、要可复现，本地库够用；要开箱即用的问答体验，再考虑托管版。

实时申报流 edgar_monitor 也值得单独一说：它看的是「过去几分钟 SEC 收到了什么」，官方在 Tools Reference 里标注 No other financial data MCP server offers this。配合 edgar_filing 就能组成事件监听——新 8-K 进来立刻拆开看 items 字段是 Item 2.02（业绩发布）还是 Item 1.05（网络安全事件）。库本身能解析的申报类型，README 列了四大件：13F 机构持仓（一行一个持仓）、Form 4 内部人交易（买卖、行权、授予逐笔）、N-PORT 基金组合、8-K 事件与业绩附件，全部输出成带类型的对象或 DataFrame。

收尾前把坑列全

身份未配置：服务器起不来，日志会提示配 EDGAR_IDENTITY。Desktop 找不到 Python：配置里写绝对路径。跑错模块入口：edgar.ai.mcp 不能直接 -m 执行，用 edgartools-mcp。版本过旧的报错：官方排障页写明 Output validation error: outputSchema defined but no structured output returned 出现在 v5.25.1 及更早版本，升级即解。想看服务器日志：macOS Desktop 的日志在 ~/Library/Logs/Claude/mcp-server-edgartools.log。Docker 部署一行环境变量搞定：FROM python:3.12-slim + pip install "edgartools[ai]" + ENV EDGAR_IDENTITY，官方文档有完整 Dockerfile。

本文依据 EdgarTools 官方文档（edgartools.readthedocs.io 的 MCP Setup 与 Tools Reference 页）与 GitHub 仓库 README 整理，实测记录来自 2026-10-22 Linux + Python 3.11 环境，版权归原作者所有。

评论 (0)