SEC EDGAR Filings

SEC EDGAR MCP 服务

一个只读的 Model Context Protocol 服务，通过标准输入输出运行，接收股票代码，将其解析为 SEC 的中央索引键（CIK），并返回带有 EDGAR 官方链接的申报元数据。它提供三个工具、五种资源和三个提示词。无需 API 密钥：SEC EDGAR 是公开的，且该服务只会通过描述性 User-Agent 标识自身。服务不会读取、下载或总结申报内容；它只会告诉你有哪些申报，以及它们在 sec.gov 上的位置。

已发布到 PyPI，包名为 mcp-server-edgar，并以 io.github.SudiptoHaldar/mcp-server-edgar 的名称列入 Official MCP Registry。

安装和运行

该服务是一个带有控制台入口点的 Python 包。最简单的运行方式是使用 uv，它会在需要时获取 Python 3.11 或更高版本：

uvx mcp-server-edgar

或者将其安装到任何装有 Python 3.11 或更高版本的环境中：

pip install mcp-server-edgar
mcp-server-edgar

可执行文件通过标准输入和标准输出使用 MCP，设计为由 MCP 客户端启动，因此单独运行时会等待客户端连接。若要交互式试用，请使用 MCP Inspector：

npx -y @modelcontextprotocol/inspector uvx mcp-server-edgar

配置 MCP 客户端

Claude Desktop 和大多数其他使用 JSON 配置的客户端都需要一个 mcpServers 条目。可选的 env 块用于设置 SEC 公平访问联系信息（参见配置）：

{
  "mcpServers": {
    "sec-edgar": {
      "command": "uvx",
      "args": ["mcp-server-edgar"],
      "env": {
        "MCP_EDGAR_USER_AGENT": "acme-research/1.0 ([email protected])"
      }
    }
  }
}

Claude Code：

claude mcp add sec-edgar -- uvx mcp-server-edgar

工具

这三个工具均为只读，并会返回一个 JSON 对象，其中的 status 字段说明了处理结果（参见结果和错误）。年份始终指申报日期，即 SEC 收到申报的日期，而非申报所涉及的期间。

get_latest_filing — 最新 SEC 申报

获取某个股票代码的最新申报，可选按指定表单类型筛选。

参数	类型	默认值	含义
ticker	string	必填	股票代码，例如 AAPL；大小写和首尾空格会被忽略；BRK.B 和 BRK-B 等价
forms	list of strings	所有表单	精确的表单类型，不区分大小写：["10-K"] 会匹配 10-K，但不会匹配 10-K/A
cik	string or integer	无	SEC CIK（1–10 位数字），仅在返回 ambiguous 时使用，用于从候选项中选定一个；该 CIK 必须列在该股票代码下

调用示例 get_latest_filing("AAPL", ["10-K"])；以下为删节后的结果，数值截至 2026-11-01：

{
  "status": "ok",
  "company": {"cik": "0000320193", "name": "Apple Inc.", "ticker": "AAPL", "exchange": "Nasdaq"},
  "forms": ["10-K"],
  "filing": {
    "form": "10-K",
    "filing_date": "2025-10-31",
    "report_date": "2025-09-27",
    "accession_number": "0000320193-25-000079",
    "filing_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.htm",
    "primary_document_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/aapl-20250927.htm"
  },
  "message": "Newest 10-K by Apple Inc. (AAPL): filed 2025-10-31."
}

如果公司没有所请求表单类型的申报，filing 将为 null。

list_filings_by_year — 按年份查看申报文件

公司在一个日历年内提交的所有申报文件，按时间从新到旧排列，分页显示。

参数	类型	默认值	含义
ticker	string	必填	同上
year	integer	必填	申报日期所在的日历年，须为 1993 年或之后；未来年份会返回空列表
forms	list of strings	所有表单	同上
limit	integer	100	每页条目数；较大的值会被限制为服务端上限
offset	integer	0	要跳过的申报文件数；传入上一结果的 next_offset
cik	string or integer	无	同上

年份指申报年份，而非财年：Apple 截至 2025 年 9 月的财年 10-K 于 2025-10-31 提交，因此属于 year=2025；财年为 2025、于 2026 年 1 月提交的 10-K 则属于 year=2026。较早年份会自动从 SEC 的历史文件中提供。

调用示例 list_filings_by_year("AAPL", 2025, ["10-K", "10-Q"])；以下为删节后的结果，数据截至 2026-11-01：

{
  "status": "ok",
  "company": {"cik": "0000320193", "name": "Apple Inc.", "ticker": "AAPL", "exchange": "Nasdaq"},
  "year": 2025,
  "forms": ["10-K", "10-Q"],
  "limit": 100,
  "offset": 0,
  "total_count": 4,
  "returned_count": 4,
  "next_offset": null,
  "filings": [
    {
      "form": "10-K",
      "filing_date": "2025-10-31",
      "report_date": "2025-09-27",
      "accession_number": "0000320193-25-000079",
      "filing_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.htm",
      "primary_document_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/aapl-20250927.htm"
    }
  ],
  "message": "Apple Inc. (AAPL): 4 filings of form 10-K, 10-Q with a filing date in 2025."
}

要获取下一页，请再次调用并将 offset 设为 next_offset，直到其值为 null。各页之间不会重叠。没有申报文件的年份会返回 ok，且 total_count 为 0。

list_form_types — EDGAR 表单类型

最近几个季度提交的 EDGAR 申报类型代码，按常见程度从高到低排列。可用它了解 forms 接受哪些值：form 与 EDGAR 使用的代码完全一致（10-K、10-K/A、SCHEDULE 13G/A、424B2、NPORT-P）。

参数	类型	默认值	含义
query	string	无	对代码和描述进行不区分大小写的文本匹配；"10-K" 会列出 10-K、10-K/A、10-KT 等；"/A" 会列出修订文件
limit	integer	100	每页条目数
offset	integer	0	要跳过的条目数；传入上一结果的 next_offset

此目录是随软件包附带的快照，统计发行版发布前已完成的四个季度的数据，并在每次发布时更新；catalogue.generated_on 和 catalogue.quarters 会说明对应的信息。调用此工具不会向 SEC 发出请求。已知表单编号的 description 和 topics 来自 SEC Forms List，否则为 null。

调用示例 list_form_types("10-K")；以下为删节后的结果，数据截至 2026-11-01：

{
  "status": "ok",
  "query": "10-K",
  "total_count": 6,
  "returned_count": 6,
  "next_offset": null,
  "catalogue": {"generated_on": "2026-11-01", "quarters": ["2025Q4", "2026Q1", "2026Q2", "2026Q3"]},
  "form_types": [
    {"form": "10-K", "description": "Annual report pursuant to Section 13 or 15(d)", "amendment": false, "filings": 6723},
    {"form": "10-K/A", "description": "Annual report pursuant to Section 13 or 15(d)", "amendment": true, "filings": 616}
  ],
  "message": "6 form types match '10-K' in 2025Q4-2026Q3."
}

结果与错误

每个工具都会返回一个 JSON 对象。预期内的情况会通过 status 报告，而不会作为协议错误返回，因此客户端可以据此采取相应操作：

status	含义	还包含
ok	请求成功	如上所示的 company，以及 filing / filings / form_types
not_found	SEC 未将该股票代码列为发行人	—
ambiguous	多个发行人使用同一股票代码；未选择任何一个	candidates：{cik, name, ticker, exchange} 列表；使用选定的 cik 再次调用
invalid_input	发出请求前拒绝了某个参数	field：有问题的参数
upstream_error	SEC EDGAR 未能及时响应、进行了限流或返回了错误数据	retryable（布尔值）和 retry_after_seconds（可能为 null）

每个对象还包含一条简短的 message。申报文件记录始终包含 form、filing_date、report_date（所涵盖的期间，仅供参考，可能为 null）、accession_number 和 filing_url（sec.gov 上的官方申报索引页）；当 SEC 列出了主文档且文件名安全时，primary_document_url 会指向该文档，否则为 null。

资源

可以将资源作为上下文附加的客户端，无需调用工具即可直接读取这些 JSON 文档。它们与工具由同一代码路径构建，因此资源和对应工具的结果始终一致。

URI	Payload
edgar://companies/{ticker}/profile	{cik, name, ticker, exchange, tickers}：发行人的身份信息，以及 SEC 在该 CIK 下列出的所有 ticker（GOOGL → ["GOOGL", "GOOG"]）
edgar://companies/{ticker}/latest	{company, filing}：与 get_latest_filing(ticker) 返回的 company 和 filing 完全一致；若发行人没有申报文件，则 filing 为 null
edgar://issuers/{cik}/profile	按 CIK 查找的资料（接受任意 1–10 位数字的写法）
edgar://issuers/{cik}/latest	按 CIK 查找的最新申报文件
edgar://form-types	{catalogue, form_types}：完整的内置目录，不分页

ticker 存在歧义时，请使用 edgar://issuers/{cik}/… 路由；该 CIK 必须列在 SEC ticker 映射表中。资源没有 status 封装：未知 ticker、格式错误或未列出的 CIK，或不匹配的 URI，都会产生资源未找到错误；有歧义的 ticker 或 SEC 服务中断会产生资源错误。两种错误携带的消息文本均与工具使用的相同。

提示词

提示词是可重复使用的指令，由用户从客户端的提示词菜单中选择；客户端会插入渲染后的文本，然后模型使用工具。提示词不包含实时数据。

提示词	标题	参数	渲染后的文本要求模型
review_latest_filing	审阅最新 SEC 申报文件	ticker（必填）	调用 get_latest_filing，引用表格类型和 filing_date，链接 filing_url，将 report_date 视为所涵盖的期间，并区分申报文件中的陈述与解读
review_filings_by_year	审阅某日历年的申报文件	ticker、year（均必填）	调用 list_filings_by_year，使用 offset = next_offset 分页，直到其值为 null；按表格类型分组，总结该年度，并为每条记录添加链接
explain_form_types	说明 EDGAR 表格类型	query（可选）	调用 list_form_types，说明常见代码，指出 /A 表示修订版，且目录是带日期的快照

每条提示词末尾都包含相同的限制：仅使用元数据和 sec.gov 官方链接；服务不会读取申报文件内容；每份申报文件都要引用 EDGAR 链接；不得提供投资建议；若答案为 ambiguous，则在再次调用并提供 cik 前，先询问指的是哪家发行人。

配置

所有设置均为带默认值的环境变量。未设置或值为空时会使用默认值；值无效则会以退出代码 1 停止启动，并在 stderr 输出一行指出变量名称。

变量	默认值	可接受值	用途
MCP_EDGAR_USER_AGENT	mcp-server-edgar/<version> ([email protected])	非空，且必须包含 @	向 SEC 标识身份以遵守公平访问要求，并提供维护者联系方式；请设置为你自己的值
MCP_EDGAR_TIMEOUT_SECONDS	30	大于 0 的数字	SEC 请求的 HTTP 超时时间
MCP_EDGAR_TICKER_MAP_TTL_SECONDS	86400	大于或等于 0 的整数（0 = 不缓存）	SEC ticker 映射表的缓存时长
MCP_EDGAR_SUBMISSIONS_TTL_SECONDS	3600	大于或等于 0 的整数	公司申报记录的缓存时长
MCP_EDGAR_PAGE_CAP	100	1..1000 的整数	list_filings_by_year 和 list_form_types 返回的最大页大小
MCP_EDGAR_MAX_REQUESTS_PER_SECOND	10	1..10 的整数	请求速率上限；SEC 允许的请求速率最高为每秒 10 次，服务无法设置更高值
MCP_EDGAR_LOG_LEVEL	INFO	DEBUG、INFO、WARNING、ERROR、CRITICAL	日志级别

SEC 要求每个自动化客户端使用联系地址标识自身，因此请将 MCP_EDGAR_USER_AGENT 设置为你自己的产品名称和电子邮件地址。日志仅输出到 stderr；stdout 用于承载协议。

如何使用 SEC EDGAR

• 股票代码转 CIK：https://www.sec.gov/files/company_tickers_exchange.json，缓存一天。一个股票代码对应多个 CIK 时会报告为 ambiguous；一个 CIK 对应多个股票代码（GOOGL、GOOG）时，视为同一发行方。
• 申报文件：https://data.sec.gov/submissions/CIK##########.json（CIK 补零至十位数字），缓存一小时。较早年份的数据从申报文件中列出的历史文件读取，且只读取日期范围与所请求年份重叠的文件。
• 链接：始终返回申报文件索引页 …/Archives/edgar/data/<cik>/<accession>/<accession>-index.htm；主文档链接根据 SEC 提供的文件名构建，并会拒绝任何不是普通文件名的内容。
• 公平访问：每秒最多 10 个请求，使用描述性 User-Agent，每个进程单独进行内存缓存，并对 HTTP 429 和暂时性 5xx 响应进行有上限的退避重试。如果 SEC 仍未响应，工具会返回 upstream_error 和重试提示，而不是空结果。请参阅 SEC 的 EDGAR API 文档。

已知限制

• 仅提供元数据和链接：不提供申报文件内容、XBRL 财务数据、摘要或投资建议。
• year 指 SEC 收到申报文件的日历年份，而非其所报告的财年。
• 1993 年之前的年份（电子申报的起始年份）会被拒绝为 invalid_input。
• 只能查询 SEC 股票代码映射表中列出的发行方；没有列出股票代码的基金和私人申报方不在支持范围内，且服务绝不会查询任意 CIK。
• 表单类型目录是每次发布前生成的快照，并非实时列表。
• 仅支持 stdio 传输；没有 HTTP 端点，也不需要身份验证。
• 缓存仅在单个服务进程的生命周期内保留在内存中。
• 本项目与美国证券交易委员会无关联，也未获其认可。

开发

git clone https://github.com/SudiptoHaldar/mcp_server_edgar
cd mcp_server_edgar
uv sync
uv run pytest -q                                  # unit tests never touch the network
uv run pytest -q -m live                          # opt-in checks against the real SEC
uv run ruff check .
uv run mcp dev src/mcp_edgar/server.py            # MCP Inspector GUI
uv run python scripts/inspector_checklist.py      # 27-row CLI checklist (needs Node and network)

发布前，请刷新随项目打包的表单类型目录，然后进行构建：

uv run python scripts/refresh_form_types.py
uv build

问题和拉取请求：https://github.com/SudiptoHaldar/mcp_server_edgar/issues。

许可证

MIT，详见 LICENSE。SEC EDGAR 数据属于公有领域，此处依照 SEC 的公平访问规则提供。