sec-edgar-mcp

一个 MCP（模型上下文协议）服务器，通过流式 HTTP 提供对 SEC EDGAR 文件的自然语言访问——公司查询、文件内容、财务报表数据、内部交易以及文件间比较——因此任何 MCP 客户端（Claude Code、Claude Desktop 等）都能回答基于真实文件的真实文件研究问题，而不是基于一般知识。

作为一件作品集项目，展示了围绕一个公开、限速、无需认证的 API 的生产级工程实践：共享的两层速率限制器、合并缓存、经真实数据验证的 HTML/XML 解析，以及通过真实 LLM 客户端测试而非仅单元测试塑造的工具界面。完整的设计推理——及其背后的权衡——记录在 plans/architecture.md 中；原始需求在 reference/product_spec.md 中。

状态： 功能上已完成至里程碑 7（全部 6 个工具，已针对真实 EDGAR 数据和真实 MCP 客户端测试）。尚未部署——目前此仓库作为本地服务器运行；容器化部署是里程碑 8。

为什么选择 HTTP 而不是 stdio

SEC EDGAR 要求提供包含联系信息的合规 User-Agent，并强制实施按 IP 的速率限制（~10 请求/秒）。在 stdio 下，每个用户的本地进程都是各自独立的 IP——速率限制实际上从未被真正执行或强制。在 HTTP 下，一次部署意味着一个出口 IP、一个共享预算，以及一个能正确实现合规、速率限制和缓存的地方。这一决策——以及它所带来的一切（单进程不变量、全局 429 退避、缓存设计）——在 plans/architecture.md 的决策 0 中有详细说明。

Related MCP server: SEC EDGAR MCP

工具

每个工具的 docstring 都刻意规定了何时调用它以及它不涵盖什么——参见 src/sec_edgar_mcp/server/tools.py。服务器的顶层 instructions（位于 src/sec_edgar_mcp/server/app.py）预先声明了完整的当前范围边界，因此客户端在尝试工具之前就能了解哪些超出范围，而不是在失败尝试之后。

目前明确不在范围内（完整列表及原因见 reference/product_spec.md §7）：高管薪酬（DEF 14A 表格）、10-Q 的散文章节（如季度 MD&A）、8-K 事件类型摘要、跨公司/全文搜索，以及超过 5% 的受益所有权（Schedule 13D/13G）。

快速开始

需要 Python 3.14+ 和 uv。

uv sync

SEC EDGAR 要求提供合规的 User-Agent——如果没有，服务器会在启动时快速失败，而不是在第一次请求时静默失败：

export SEC_EDGAR_USER_AGENT="your-app-name/0.1 (you@example.com)"

运行它：

uv run python -m sec_edgar_mcp

在 127.0.0.1:8000 上启动一个流式 HTTP 服务器（可通过 SEC_EDGAR_HOST / SEC_EDGAR_PORT 配置；其他所有可调参数——速率限制、缓存 TTL、重试/退避——均见 src/sec_edgar_mcp/config.py，都有默认值，仅 User-Agent 是必需的）。

使用 MCP Inspector 试用

uv run mcp dev src/sec_edgar_mcp/__main__.py

打开一个浏览器 UI，用于直接以原始 JSON-RPC 调用每个工具——适合验证单个工具的输入/输出形状，而不适合测试 LLM 如何在工具之间进行选择。

连接到 Claude Code

在服务器运行的情况下：

claude mcp add --transport http sec-edgar-mcp http://127.0.0.1:8000/mcp

启动一个新的 claude 会话（MCP 服务器在会话启动时加载），然后问它一个真实的问题——例如 “苹果在最近两份 10-K 中关于供应链的风险因素措辞是否发生了变化？” 或 “显示英伟达高管在过去 90 天内所有按价值排序的 Form 4 内部出售。”

开发

uv run pytest          # unit + tool-layer tests (mocked EDGAR, no network)
uv run pytest -m live  # opt-in tests against real EDGAR
uv run ruff check .
uv run ruff format .
uv run mypy --strict src tests

四层自动化测试，外加第五层手动测试——将运行中的服务器连接到真实的 MCP 客户端并询问自然语言问题——这实际上发现了本仓库历史中修复的几个错误（具体见 plans/architecture.md 的测试部分和最近的提交消息）。tests/fixtures/filings/ 保存了约 10 份真实的、已提交的 10-K 和 Form 4 文件，涵盖不同的申报者规模和时代——解析器是针对真实数据验证的，而不是合成 HTML。

项目结构

src/sec_edgar_mcp/
  config.py        # required SEC_EDGAR_USER_AGENT, everything else defaulted
  domain/           # Pydantic models (CIK, Filing, InsiderTransaction, FinancialFact, ...)
  edgar/            # rate limiter, cache, HTTP client, endpoint wrappers, parsers
  services/         # composition logic (resolve, compare, insiders, financials)
  server/           # MCPServer, @mcp.tool() adapters, logging, scope instructions
tests/
  fixtures/filings/ # ~10 real, committed SEC filings
plans/architecture.md    # full design reasoning and milestone history
reference/product_spec.md # original requirements + recorded scope decisions