pequod-mcp

pequod-mcp — “the Gam”

面向 Agent 的 SEC 一手来源 ETF 持仓数据与标识符交叉映射。

一个 MCP（Model Context Protocol）服务，为 AI Agent 提供任意美国注册 ETF 的完整持仓，数据直接来自 SEC EDGAR N-PORT 文件——不是只抓取前 10 大持仓——还提供一组标识符交叉映射工具（ticker、CUSIP/SEDOL、FIGI → 已解析的 symbol），数据由 OpenFIGI 和 SEC 参考数据支持。通过 stdio 在本地运行；无需订阅供应商的市场数据服务。

工具

工具	功能	数据源
lookup_cik	Ticker → SEC CIK + 实体元数据（名称、SIC、交易所、财年结束日期）	SEC company_tickers.json + submissions API
resolve_ticker	原始 ticker + 可选交易所代码 → Yahoo 约定格式的 symbol，并经过验证	交易所后缀映射（纯字符串映射）+ SEC + OpenFIGI
resolve_cusip	CUSIP（或 SEDOL）→ symbol，并通过多个数据源交叉验证	OpenFIGI（一次批量请求）+ SEC 名称/ticker 一致性
resolve_figi	Bloomberg FIGI → symbol，并通过多个数据源交叉验证	OpenFIGI + SEC 名称/ticker 一致性
get_etf_holdings	任意美国 ETF → 其最新月度 N-PORT 文件中的完整持仓列表（名称、ticker、ISIN、FIGI、LEI、份额、美元价值、占净资产比例、国家、货币）	SEC EDGAR N-PORT XML

所有工具均为只读。

验证方式

交叉映射结果无需任何市场数据供应商即可验证：

1. SEC 注册信息核查 — 如果映射出的 ticker 是美国 SEC 注册实体，company_tickers.json 中的实体名称必须与 OpenFIGI 证券名称一致。名称明显不符时会否决该映射（verification: "name_veto"），而不是返回看似合理的错误 symbol。
2. OpenFIGI 映射 — 对于 SEC 注册信息中没有的非美国 symbol，直接依据 OpenFIGI 映射进行验证，并标记为 verification: "openfigi"，方便区分不同的置信度等级。

Yahoo Finance symbol 格式（.SW、.T、.L 等后缀）仅通过字符串约定处理——默认流程不会调用 Yahoo 网络接口。

安装

# with uv
uv pip install pequod-mcp

# or with pip
pip install pequod-mcp

直接运行（stdio）：

pequod-mcp

可选：OpenFIGI API 密钥

不设置密钥也可使用该服务（但会受到 OpenFIGI 匿名速率限制）。如需更高用量，可在 https://www.openfigi.com/api 免费获取密钥并设置：

export API_OpenFIGI="your-key-here"

可选：Yahoo 增强组件

可选择启用一个附加组件，为交叉映射结果添加实时 Yahoo 行情信息块。该功能默认关闭，除此之外不会使用 Yahoo；启用即表示你自行接受 Yahoo Finance 使用条款。

pip install 'pequod-mcp[yahoo]'
export PEQUOD_YAHOO_VERIFY=1

在 Claude 中配置

Claude Desktop（claude_desktop_config.json）或任何使用 stdio 传输的 MCP 客户端：

{
  "mcpServers": {
    "pequod": {
      "command": "pequod-mcp",
      "env": {
        "API_OpenFIGI": "your-key-here"
      }
    }
  }
}

Claude Code：

claude mcp add pequod -e API_OpenFIGI=your-key-here -- pequod-mcp

Agent 工作流示例

1. “SCHD 实际持有哪些资产？”

Agent: lookup_cik("SCHD")
  → { cik: "0000884394", entity_name: "SCHWAB STRATEGIC TRUST", found: true }
Agent: get_etf_holdings("SCHD", cik="0000884394")
  → { fund_name, report_date, source_url (the actual EDGAR filing),
      total_holdings: ~100, holdings: [ { name, ticker, isin, figi,
      balance, value_usd, pct_val, ... } ] }

Agent 会获取每项持仓及其权重，以及可用于引用的 EDGAR URL——可追溯至一手来源，方便审计。

2. “我有一个来自 13F 的 CUSIP——这是什么股票？”

Agent: resolve_cusip("594918104")
  → { yahoo_symbol: "MSFT", verified: true, verification: "openfigi+sec",
      company_name: "MICROSOFT CORP", cik: "0000789019",
      openfigi: { figi: "BBG000BPH459", ... } }

如果 OpenFIGI 的映射与 SEC 注册信息中 ticker 所属实体不一致，该工具会拒绝返回结果（verification: "name_veto"），而不是给出错误的 symbol。

3. “比较两只股息 ETF 的持仓重合情况。”

Agent: get_etf_holdings("SCHD")   → complete holdings A
Agent: get_etf_holdings("VYM")    → complete holdings B
Agent: joins on isin (or ticker), computes overlap weight, reports the
       shared names — all from two tool calls, both citing SEC filings.

数据来源

• 所有持仓数据均来自 SEC EDGAR 一手来源（Form N-PORT 文件、submissions API 和 company_tickers.json）。标识符交叉映射来自 OpenFIGI API（FIGI 是一项开放的 OMG 标准）。
• 输出中不包含 CUSIP。 工具输出包含 ticker、ISIN、FIGI 和 LEI；底层文件中的 CUSIP 字段会被刻意剔除。
• 遵守 SEC 公平访问政策： 每个请求都声明 User-Agent；请求频率远低于 EDGAR 公布的速率限制；并在磁盘上缓存 company_tickers.json（24 小时）和 N-PORT 文档（30 天——已提交的文档不可更改）。缓存位于模块旁的 .cache/ 中，可通过 PEQUOD_CACHE_DIR 覆盖。
• 出错即明确报错： 如果无法访问 EDGAR，或无法解析文件，工具会返回错误。不会使用降级或部分回退数据源——你要么获取有文件依据的数据，要么收到明确的失败信息。
• N-PORT 文件有发布延迟（持仓数据通常滞后约 1–2 个月）。report_date 和 source_url 字段会明确指出所查看的具体期间。
• 不构成投资建议。 此服务转发公开的监管文件和开放的标识符映射；请在做出投资决策前独立核实。

环境变量

变量	默认值	用途
API_OpenFIGI	（未设置）	OpenFIGI API 密钥（可提高速率限制）
PEQUOD_CACHE_DIR	模块旁的 .cache/	磁盘缓存位置
PEQUOD_YAHOO_VERIFY	（关闭）	选择启用 Yahoo 数据补充（需要 [yahoo] extra）
LOG_LEVEL	INFO	服务日志详细程度

开发

pip install -e '.[dev]'
pytest            # fully offline — fixture filings, no live network

许可证

Apache-2.0——详见 LICENSE。版权所有 2026 AB Evergreen Analytics LLC。