SEC EDGAR MCP

<div align="center">

# SEC EDGAR MCP

</div>


<p align="center">
  <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg" />
  <img alt="Python: 3.9+" src="https://img.shields.io/badge/python-3.9+-brightgreen.svg" />
  <img alt="Platform: Windows | Mac | Linux" src="https://img.shields.io/badge/platform-Windows%20%7C%20Mac%20%7C%20Linux-lightgrey.svg" />
  <img alt="Build Status" src="https://img.shields.io/badge/build-passing-brightgreen.svg" />
  <a href="https://pypi.org/project/sec-edgar-mcp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/sec-edgar-mcp.svg" /></a>
</p>

<div align="center">
    <a href="https://www.loom.com/share/17fcd7d891fe496f9a6b8fb85ede66bb">
      <img style="max-width:300px;" src="https://cdn.loom.com/sessions/thumbnails/17fcd7d891fe496f9a6b8fb85ede66bb-7f8590d1d4bcc2fb-full-play.gif">
    </a>
    <a href="https://www.loom.com/share/17fcd7d891fe496f9a6b8fb85ede66bb">
      <p>SEC EDGAR MCP - 演示 - 观看视频</p>
    </a>
</div>

## 简介 📣

SEC EDGAR MCP 是一个开源的 MCP 服务器，它将 AI 模型连接到 [SEC EDGAR 备案](https://www.sec.gov/edgar) 的丰富数据集。 EDGAR（电子数据收集、分析和检索）是美国证券交易委员会 (SEC) 用于公司提交官方备案的主要系统。它包含数百万份备案文件，并通过提供免费的公众访问公司财务信息的途径，“提高证券市场的效率、透明度和公平性”。该项目使 AI 助手 (LLM) 可以访问大量上市公司数据，用于财务研究、投资洞察和公司透明度用例。

使用 [模型上下文协议 (MCP)](https://modelcontextprotocol.io/) – 一种开放标准，它“支持 LLM 应用程序与外部数据源和工具之间的无缝集成” – SEC EDGAR MCP 服务器公开了一组由官方 [SEC EDGAR REST API](https://www.sec.gov/edgar/sec-api-documentation) 支持的工具。 在底层，它利用 [Python secedgar SDK](https://github.com/sec-edgar/sec-edgar)（SEC API 的非官方包装器）来获取公司备案和财务事实等数据。 这意味着 AI 代理可以提出诸如“苹果公司最新的 10-K 备案是什么？”或“显示特斯拉 2021 年的总收入”之类的问题，并且 MCP 服务器将直接从 EDGAR 的官方数据中检索答案。

## 用法 🚀

一旦 SEC EDGAR MCP 服务器运行起来，您就可以使用任何兼容 MCP 的客户端（例如 AI 助手或 MCP CLI 工具）连接到它。 客户端将发现可用的 EDGAR 工具，并可以调用它们以从 SEC 备案中获取实时数据。 例如，AI 助手可以使用此服务器来获取公司最近的备案或查询特定的财务指标，而无需手动进行网络搜索。

**演示**：这是一个 AI 助手使用 SEC EDGAR MCP 检索 Apple 最新备案和财务事实的演示（点击观看视频）：

在上面的演示中，助手使用 Apple 的 CIK 调用 get_submissions 工具，然后使用 get_company_concepts 来获取特定的财务概念，展示了如何实时检索和呈现 EDGAR 数据。 📊

## 安装 🛠

请按照以下步骤设置并运行 SEC EDGAR MCP 服务器：

1. **克隆存储库**：
   ```bash
   git clone https://github.com/yourusername/sec-edgar-mcp.git
   cd sec-edgar-mcp

2. 安装依赖项：确保您已安装 Python 3.9+。 安装所需的软件包，包括 MCP 框架 和 secedgar SDK：

   pip install mcp secedgar
   

3. 配置 SEC EDGAR API 访问：SEC API 要求所有请求都提供 User-Agent 字符串。 在项目目录中创建一个 .env 文件并添加您的用户代理信息：

   SEC_API_USER_AGENT="您的姓名 (your.email@domain.com)"
   

   这会将您的应用程序标识给 SEC（替换为您的详细信息）。 服务器将从环境中加载此信息以验证 EDGAR 的身份。

4. 启动 MCP 服务器：启动服务器以开始侦听 MCP 客户端。 例如：

   mcp install sec_edgar_mcp/server.py --env-file .env --name "SEC EDGAR MCP Server"
   

   运行后，服务器将注册其工具（见下文）并等待客户端连接。 您应该会看到日志指示它已准备就绪。 🎉

现在服务器已启动并运行，可以为任何 MCP 客户端提供 EDGAR 数据！ 您可以使用 MCP CLI 或 AI 平台（例如 Claude Desktop）连接到 localhost（或适当的传输）并开始发出工具调用。

工具 🔧

SEC EDGAR MCP 公开了 SEC EDGAR API 中的多个工具（函数）。 这些工具允许检索不同类型的数据：

• 公司提交 – 公司的最新备案和元数据（按 CIK）。
• 公司概念 – 公司特定财务概念（XBRL 标签）的详细数据。
• 公司事实 – 公司所有可用的财务事实。
• XBRL 框架 – 跨公司或时间范围的财务概念的聚合数据。

每个工具都定义了名称、描述和输入参数。 AI 助手可以通过 MCP 的 JSON-RPC 接口调用它们。 以下是工具列表，其中包含详细信息和如何调用它们的示例（点击展开）：

<details> <summary><strong>📁 get_submissions</strong> – 获取公司的提交（备案历史记录）</summary>

描述：返回给定公司的提交历史记录，由其 CIK 标识。 响应包括公司信息（名称、股票代码等）和最近的备案（表格、日期、报告期等）。 这对于获取公司已提交的最新备案（10-K、10-Q、8-K 等）的列表非常有用。

示例调用 (MCP JSON-RPC)：

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "get_submissions",
    "arguments": { "cik": "0000320193" }
  }
}

示例响应（已截断）：

{
  "cik": "0000320193",
  "name": "Apple Inc.",
  "tickers": ["AAPL"],
  "exchanges": ["Nasdaq"],
  "filings": {
    "recent": {
      "form": ["10-K", "10-Q", ...],
      "filingDate": ["2023-10-26", "2023-07-27", ...],
      "reportDate": ["2023-09-30", "2023-06-30", ...],
      "primaryDocument": ["aapl-2023-10k.htm", "aapl-2023-q3.htm", ...],
      ... 
    }
  }
}

在此示例中，为 Apple（CIK 0000320193）调用 get_submissions 返回一个 JSON，其中包含 Apple 的基本信息及其最新的 10-K 和 10-Q 备案列表（及其日期和文档名称等）。 </details>

<details> <summary><strong>💡 get_company_concepts</strong> – 获取公司报告的特定概念</summary>

描述：获取给定公司单个财务概念（XBRL 标签）的所有报告值。 您必须指定公司的 CIK、会计分类法（例如，美国 GAAP 财务的 us-gaap）和特定标签（概念名称，例如 AccountsPayableCurrent）。 响应包括有关该概念的元数据和报告值的时序（按年/季度）。

示例调用 (MCP JSON-RPC)：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_company_concepts",
    "arguments": { 
      "cik": "0000320193",
      "taxonomy": "us-gaap",
      "tag": "AccountsPayableCurrent"
    }
  }
}

示例响应（已截断）：

{
  "cik": 320193,
  "taxonomy": "us-gaap",
  "tag": "AccountsPayableCurrent",
  "label": "Accounts Payable, Current",
  "description": "The carrying value of accounts payable as of the balance sheet date.",
  "entityName": "Apple Inc.",
  "units": {
    "USD": [
      { "end": "2022-09-24", "val": 64220000000, ... },
      { "end": "2021-09-25", "val": 54763000000, ... },
      ...
    ]
  }
}

上面显示了 Apple 最近年末日期的“应付账款，流动”（us-gaap 分类法）的美元值。 units -> USD 下的每个条目都包含期间结束日期和报告的值。 此工具允许 AI 从公司财务报表中检索以备案形式报告的特定项目。 </details>

<details> <summary><strong>🗃️ get_company_facts</strong> – 检索公司的所有事实（完整的 XBRL 事实集）</summary>

描述：返回给定公司（按 CIK）的所有可用 XBRL 事实。 这是该公司财务事实的综合数据集，包括多个分类法（例如，dei 中的一般公司信息、us-gaap 中的财务报表等）。 响应是一个嵌套的 JSON，按分类法分组事实，然后按单个标签分组，并包含值的数组。

示例调用 (MCP JSON-RPC)：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_company_facts",
    "arguments": { "cik": "0000320193" }
  }
}

示例响应（已截断）：

{
  "cik": 320193,
  "entityName": "Apple Inc.",
  "facts": {
    "dei": {
      "EntityCommonStockSharesOutstanding": {
        "label": "Entity Common Stock, Shares Outstanding",
        "units": { "shares": [ ... ] }
      },
      "EntityPublicFloat": {
        "label": "Entity Public Float",
        "units": { "USD": [ ... ] }
      },
      ...
    },
    "us-gaap": {
      "AccountsPayableCurrent": {
        "label": "Accounts Payable, Current",
        "units": { "USD": [ { "end": "2022-09-24", "val": 64220000000 }, ... ] }
      },
      "AccountsReceivableNet": {
        "label": "Accounts Receivable, Net",
        "units": { "USD": [ ... ] }
      },
      ...
    }
  }
}

此截断的示例显示了 Apple 的 get_company_facts 输出的结构。 它包括 dei 事实（如已发行股份）和 us-gaap 财务事实（如应付账款、应收账款等），每个事实都有其值。 AI 可以使用它从公司备案中提取一系列数据点（尽管通常数据量超过所需，因此对于有针对性的问题，最好使用 get_company_concepts 定位特定概念）。 </details>

<details> <summary><strong>🌐 get_xbrl_frames</strong> – 查询 XBRL“框架”（跨实体或时间的数据）</summary>

描述：检索给定财务概念在所有公司或设定时间范围内的相关数据。 在 EDGAR 的 API 中，“框架”本质上是特定标签、单位和期间的聚合（例如，所有公司在 2023 年第一季度的收入值）。 您需要指定分类法、标签、单位（例如 USD）、年份和期间（年度或季度）。 此工具返回在该期间报告该概念的所有实体的数据点列表。

示例调用 (MCP JSON-RPC)：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_xbrl_frames",
    "arguments": { 
      "taxonomy": "us-gaap",
      "tag": "AccountsPayableCurrent",
      "unit": "USD",
      "year": 2019,
      "quarter": 1
    }
  }
}

示例响应（已截断）：

{
  "taxonomy": "us-gaap",
  "tag": "AccountsPayableCurrent",
  "uom": "USD",
  "ccp": "CY2019Q1I",  <!-- Calendar Year 2019, Q1, Instantaneous -->
  "data": [
    {
      "cik": 1555538,
      "entityName": "SUNCOKE ENERGY PARTNERS, L.P.",
      "end": "2019-03-31",
      "val": 78300000
    },
    {
      "cik": 11199,
      "entityName": "BEMIS CO INC",
      "end": "2019-03-31",
      "val": 465700000
    },
    ... (数千个数据点) ...
  ]
}

此示例要求提供 2019 年第一季度“应付账款，流动”（以美元计）的值。 结果包括在 2019 年第一季度末报告该指标的所有公司的数组，每个公司都有其 CIK、名称和值。 有很多公司（在本例中，框架返回了 3388 个数据点）。 这对于广泛的分析（例如，查找行业总数或比较同行）很有用，尽管 LLM 通常会过滤或请求特定公司的数据，而不是一次检索数千个条目。 </details>

注意：上面的 JSON 结构直接从 SEC EDGAR API 通过 secedgar SDK 返回。 MCP 服务器不会更改数据，因此您会获得与官方 API 相同的字段。 所有工具都需要有效的 CIK（中央索引密钥）才能进行公司特定的查询 – 如果您只知道股票代码或名称，可以使用 SEC 的 CIK 查找工具。

架构 🏗️

SEC EDGAR MCP 服务器充当 AI（MCP 客户端）和 SEC 的 EDGAR 后端之间的中间人：

• 🔸 MCP 客户端：可以是 AI 助手（如带有 MCP 插件的 Claude 或 GPT-4）或任何使用 MCP 协议的应用程序。 客户端发送 JSON-RPC 请求以调用工具（例如 get_submissions）并接收 JSON 结果。

• 🔸 MCP 服务器 (SEC EDGAR MCP)：此服务器（您正在阅读的项目）定义了 EDGAR 工具并处理传入的工具请求。 当收到请求时，服务器使用 secedgar Python SDK 调用 SEC EDGAR REST API，然后通过 MCP 返回响应。

• 🔸 SEC EDGAR REST API：官方 SEC 端点 (data.sec.gov)，以 JSON 格式提供 EDGAR 数据。 secedgar 库与此 REST API 通信，并遵守其 使用策略（包括速率限制和用户代理标识）。

工作原理：MCP 客户端首先查询服务器的工具列表（发现诸如 get_submissions 等函数）。 然后，AI 可以决定使用适当的参数按名称调用工具。 服务器接收 tools/call 请求，通过 secedgar 执行相应的 EDGAR API 调用，并返回数据。 此响应以结构化的 JSON 格式发送回 AI 客户端，AI 可以读取该格式并将其合并到其答案或推理中。

从本质上讲，SEC EDGAR MCP 弥合了自然语言问题和原始 SEC 备案数据之间的差距。 通过遵守 MCP，它标准化了 AI 模型获取真实世界财务数据的方式，使用官方来源的信息来获得准确和最新的答案。

参考资料 📚

• SEC EDGAR – 关于 EDGAR，SEC.gov (2024)。 EDGAR 是 SEC 用于电子公司备案的数据库。

• 模型上下文协议 (MCP) – 官方文档和 SDK。 ModelContextProtocol.io – 用于将 LLM 连接到工具的开放标准。

• SEC EDGAR API Python SDK (secedgar) – SEC EDGAR REST API 的非官方 Python 包装器。 GitHub 仓库, 文档。

许可证 ⚖️

本项目根据 MIT 许可证 获得许可。 您可以自由使用、修改和分发它。 有关详细信息，请参见 LICENSE 文件。

© 2025 Stefano Amorelli – 在 MIT 许可证下发布。 尽情享受吧！ 🎉