Oxford Ledge

Oxford Ledge MCP 服务

最后更新： 2026-10-10 版本： 3.8.3（仅限政府公共数据的功能范围；CUSIP + 第三方 FRED 例外）

向你的助手提问；它会查阅公开记录。这个软件包让 Claude、Codex、Cursor 或任何支持 Model Context Protocol 的客户端都能查询 SEC 文件与基本面数据、13F 持仓、内幕交易、BDC 贷款账簿，以及 Treasury、FRED、FDIC、USAspending、USPTO 和 CFTC 数据，并在回答中注明来源。

安装： pip install oxford-ledge-mcp（Python 3.9 或更高版本，无第三方依赖项）。连接： 各客户端的分步设置指南和免费 API 密钥，见 oxfordledge.com/mcp。注册信息： 已列入官方 MCP Registry，名称为 com.oxfordledge/oxford-ledge；注册信息指向此软件包，并将托管服务 https://www.oxfordledge.com/mcp 列为远程服务。

所有 Oxford Ledge 套餐均可免费使用，且有几个工具完全无需账户即可运行（见下文的 独立模式）。接下来是发行说明；之后将介绍工具涵盖的内容、三种模式、工具列表和数据条款。

发行说明

当前版本为 3.8.3。 此补丁版本基于 3.8.2，未新增、重命名或移除任何工具或参数。修复： 在 get_fundamentals 的 LongTermDebt 序列中，如果申报者某年只标记了非流动部分，现在只有在申报者自己的标签能够证明两者等同的情况下（至少有一年包含全部三项事实，且所有此类年份都一致），才会将该年的 LongTermDebtCurrent（us-gaap LongTermDebt 自身定义中的组成部分）加到该年数值中，并且 concepts 会注明该单元格经过合并；申报者的序列仍可能混合包含合并值和仅包含非流动部分的年份，商业票据和短期借款仍不会被相加。修复： get_sec_filings 遇到未知股票代码或 CIK 时会拒绝请求（DATA_UNAVAILABLE），而不是将空列表作为成功结果返回。新增： get_yield_curve 现在包含 unit: "percent"。

3.8.2（上一个版本）。 此补丁版本基于 3.8.1，未新增、重命名或移除任何工具或参数，也未重命名或移除任何数据键。新增： ol_bdc_top_borrowers 的行会保留 fair_value_holders 和 inactive_holder_fair_value（已合并贷方冻结估值中未计入跨持有人总和的部分）。修复： 告知操作员在哪里获取 API 密钥的拒绝提示，之前指向 Oxford Ledge 网站已移除的屏幕控件；现在提示“按 K 或打开 Settings -> API keys”，这是网站和托管服务所列出的入口。更改： get_debt_maturities 和 get_capital_allocation 的描述文本现使用定价页面上的套餐名称“Researcher”；[Tier: plus] 前缀和拒绝提示仍使用 plus，即 API 接受的套餐键。本版本的其他允许列表变更仅适用于托管服务的匿名回答，不适用于此软件包（见 CHANGELOG）。

3.8.1。 此补丁版本基于 3.8.0，未新增、重命名或移除任何工具、参数或数据键。更改： 此软件包发往 Oxford Ledge 的所有请求——REST 代理调用和托管工具的两个请求环节，无论是否使用密钥——现在都会在 User-Agent 中标明软件包版本，使用 OxfordLedgeMCP/1.0 (oxford-ledge-mcp 3.8.1)，而非固定值 OxfordLedgeMCP/1.0，因此可以根据报告中的调用匹配发出该调用的版本；它发往 SEC EDGAR 和 FRED 的请求没有变化。更改： get_corporate_events 的 tool_notes 现在多包含一条说明：空（或 null）description 表示尚未读取该文件的文本（尚未获取，或无法提取），绝不表示该文件没有内容——打开 sourceUrl 即可阅读。文档： 本 README 现在注明了官方 MCP Registry 列表（见上文）。 3.8.0。 此版本还包含下文所述的 3.7.2 版本中的所有内容，该版本从未单独发布——从 3.7.1 升级即可获得两者。**变更：**每个工具的描述现在都是一张不超过 1,300 个字符的简短说明卡，介绍工具的返回内容、关键参数、数据来源，以及调用前需了解的一项注意事项，让已连接的会话在首次调用前消耗的令牌大幅减少（29 条描述的总长度从约 70,900 个字符降至约 23,700 个字符）。原本写在描述中的注意事项现在随每个响应放在靠近负载开头的 tool_notes 列表中；许可、再分发和拒绝声明仍在描述中原样保留。变更：response_size.over_budget 现在依据不含 tool_notes 的数据进行判断，而 chars 仍报告整个负载的字符数。没有重命名或移除任何工具、参数或数据键。

**3.7.2（并入 3.8.0，从未单独发布）。**以下变更在 3.7.1 到 3.8.0 的描述变更之间完成。移除：get_corporate_events 中的 amount 和 status——没有写入程序填充这两个字段，因此它们始终为 null。本软件包新增传递的键：get_13f_holdings 中的 filedName（提交文件中填写的发行方名称；仅当它与提供的 name 不同时出现）；get_holders 中的 shares_outstanding_period（所有权百分比计算所依据的股份数量对应的财务期间）和 other_class_rows_excluded（同一公司的其他股份类别下提交的记录，不计入总数）；get_insider_trades 的记录中的 priceApplicable（若赠与、奖励或其他代码以价格 0 提交，则为 false——提交的 0 会保留）；get_capital_allocation 中每年的 grossRepurchases 和 totalGrossRepurchases（未标记时为 null；netBuybacks 保持不变，仍是稀释的替代指标）；ol_patents 中的 last_ingested_at 和 parent_patent_number；get_fred_data 和 get_yield_curve 中的 fred_notice（FRED 的使用条款声明）。新增参数：get_insider_trades 中的 limit 和 days；ol_insider_recent_buys 中的 common_only（默认值为 true）和 min_value。**主机端变更（已安装 3.7.1 的版本也会看到）：**A 类和 B 类持仓不再混在一起（此前 Berkshire Hathaway 的 A 类持仓曾作为 B 类持有人提供）；当 M&A 读取器的置信度至少为 0.5 时，get_corporate_events 会填充 counterparty（标记为派生数据）。BDC（MCP-D）：ol_bdc_borrower_dispersion 现在每个 LENDER 返回一条记录（limit 统计贷款机构数量；分批贷款嵌套在 tranches 下；新增 lender_count、tranche_count、lender_row_basis、par_amount、cost_amount；除非 include_stale 为 true，否则会排除过期的贷款机构，并通过 stale_lenders_excluded 报告；count 现在统计贷款机构数量），对于一笔按接近成本价标记的贷款，如果其面值标记远低于成本标记，则该记录会包含 mark_basis / mark_basis_note（部分出资承诺），且不提供收益率；当账簿的公允价值无法提供时，get_bdc_holdings 的 parseQuality 为 suspect。**借款人描述：**研究撰写的描述会标明其由 AI 模型根据公开网络来源撰写，且未经抄袭检查；研究引用了付费墙或受限数据库的描述将不再提供（descriptionWithheld 会说明原因），并且在记录了来源的情况下会出现 descriptionSources。 **3.7.1。**与 3.7.0 的变更见 MIGRATING.md。没有重命名或移除任何工具、参数或键，没有参数变更，也没有发送任何新内容。Oxford Ledge 服务已经发送的六个键，现在会通过此软件包的故障关闭式输出过滤器（3.7.0 会剥离这些键）：get_bdc_list 和 get_bdc_holdings 中的 fairValueGap / fairValueGapNote——标签和说明文字，用于指出当 BDC 解析后的行数总额与申报文件中的总额相差超过 5% 时的情况，包括低估情形：totalFairValue 低于账面价值；ol_bdc_credit_quality 中的 withheld / parser_dialect_version——说明为何覆盖范围内的非应计率为 null（coverage_state 为 implausible：超过 25% 的可确定债务账面价值被标记，且被标记的贷款接近平价，这表明 Oxford Ledge 对附表的解析有误；若标记低于 85 的贷款占比超过 25%，或没有可供核验的已存档标记，则会标为 unusually_high——请检查申报文件），以及读取该季度的解析器版本；get_value_investing_fact 中的 verbatim；以及 get_insider_trades 和 ol_insider_recent_buys 中的 issuerSelfFiled——当 Form 4 使用公司的 SEC ID 自行申报时为 true，因此报告所有者字段显示的是公司名称，而非个人名称（3.7.0 提供的这些相同行没有标注；Oxford Ledge 从不将它们计入自己的总数，你也不应这么做）。在 get_insider_trades 中，如果负责响应的主机没有发送该键，则该键会缺失，而不是设为 false。描述已修正，与实际传输内容一致：get_value_investing_fact 条目会用未经来源核实的措辞转述或总结所列作者的观点（有些条目可能会重复作者本人的原话），因此除非 verbatim 为 true，否则并非逐字引文——应使用 attribution 作为署名；ol_bdc_top_borrowers 按 ACTIVE 贷款方数量排名；ol_bdc_mark_changes 指明了 fair_value_refused 排除项。描述现已说明主机端变更（已安装 3.7.0 的版本也能看到这些变更，因为它们使用的是该版本已通过过滤的键）：当申报文件没有标记可用总额，或 Oxford Ledge 存储的参考信息对应的申报文件与所提供的账簿不同，reportedTotalFairValue 为 null，而非 0；get_bdc_list 的 lastParsed 是 Oxford Ledge 最近一次写入该 BDC 注册表行的日期；MRCC（已并入 HRZN）已从 get_bdc_list 中移除；ol_bdc_mark_changes 的 filters.debt_mark_band_pts 现为 [30, 105]。3.7.0 的变更（X-OL-MCP-Tool 标头、get_bdc_holdings 分页、get_fails_to_deliver 的 end_date、_meta.response_size、对 MORTGAGE30US / AAA 的拒绝）在该文档各自的标题下。

工具覆盖范围

29 个工具，涵盖 SEC 文件与基本面数据、机构与内部人士持仓、BDC／私人信贷持仓、宏观利率，以及联邦参考数据（FDIC、USAspending、USPTO、CFTC）。自 3.1.0 起，这是一个仅使用政府公共数据的程序包：29 个工具中有 28 个由美国政府公共来源提供支持——SEC EDGAR、FRED、U.S. Treasury、FDIC、USAspending、USPTO 或 CFTC；唯一例外是 get_value_investing_fact，由 Oxford Ledge 编写（basis: ol-authored，这是一个精选语料库，包含标注出处的转述与原则，其措辞未与原始来源核实——每一行都有 author／source／attribution，且只有经原始来源核实的文本才会将 verbatim 设为 true）；整个接口中没有任何商业供应商的数据源，也不包含第三方版权数据（拒绝提供 S&P／ICE／Moody's／CBOE 的 FRED 序列；不分发 FactSet 授权的债券 CUSIP）。软件采用 MIT 许可证，由 Oxford Ledge 编写；其返回的数据受各自条款约束（见下文数据许可）。29 个工具中有 27 个无需 Oxford Ledge 账户即可使用：其中 4 个通过公共 API 完全独立运行（2 个 SEC EDGAR 工具，无需密钥；2 个 FRED 工具，需要免费的 FRED_API_KEY），另外 23 个只要将 OXFORD_LEDGE_URL 指向运行中的 Oxford Ledge 实例，即可在无需密钥的情况下使用（其中 14 个是托管 MCP 的匿名 /mcp 传输方式的名称代理，另有 9 个是未验证身份的 REST 路由代理）。只有两个 Plus 层级工具（get_debt_maturities、get_capital_allocation）需要 OXFORD_LEDGE_API_KEY。仍建议安装时采用带密钥的 API 模式：它会将调用归属到你的账户、解锁两个付费工具，也是唯一能够刷新过期 EDGAR 缓存的方式（见 get_activist_stakes）。（供应商提供的报价／估值／筛选／新闻和 CUSIP 债券查询已不再包含在程序包中——请使用托管的 Oxford Ledge MCP 服务。）

从 1.x／2.0.0／2.0.1 升级？ 请参阅 MIGRATING.md（GitHub 上的文件——此文件和 CHANGELOG.md 不包含在 wheel 或 sdist 中）。简而言之：在整个 2.x 系列中，工具名称、参数架构和配置均未改变。两项实质性变更：

1. 2.0 将共享工具注册表提取到 oxford_ledge_mcp_core 子程序包中，供可通过 pip 安装的服务和 Oxford Ledge 树内服务共同使用。用户可见行为没有变化。
2. 2.0.1 从此程序包中移除了 yfinance（它是违反服务条款的爬虫依赖项）。此前可独立运行的 11 个工具现在需要 OXFORD_LEDGE_URL。
3. 2.0.2 清理了内部重构代码；行为没有变化。

---

安装

pip install oxford-ledge-mcp

基础安装不包含任何第三方依赖（仅使用标准库，这是自 2.0.1 移除 yfinance 后的情况）。服务内置了 JSON-RPC-over-stdio 回退机制，因此开箱即用。如需使用标准的 mcp 协议库路径，请安装可选扩展：

pip install "oxford-ledge-mcp[mcp]"

如果存在 mcp 包，服务就会使用它；否则会透明地回退到内置的 stdio 循环。无论哪种方式，都需要 Python ≥ 3.9。

两种传输方式行为一致。 3.4.0 发布前的验证分别测试了两种方式，发现它们在客户端会据以判断的三处行为上存在差异；这三处差异均已在 3.4.0 中修复。在 3.4.0 中，两种传输方式都会将工具错误（AUTH_REQUIRED、INVALID_PARAMS、DATA_UNAVAILABLE、RATE_LIMITED、未知工具）标记为 isError: true，因此会根据此标记重试或中止的 Agent 框架无论使用哪种方式，都会得到相同结果；缺少必需参数的调用会被拒绝，并以 INVALID_PARAMS 指明参数名称；超出声明的 minimum / maximum 的数值也会被拒绝（见下文的参数边界——两种传输方式都不会对数值进行截断）；此外，tools/list 会在每条描述前添加派生出的 [Tier: free|plus] 前缀。如何选择：想要零依赖时使用内置循环（直接运行 pip install 或普通 uvx 时就是这种方式）；如果客户端或框架需要参考协议库自身的消息帧处理和架构验证，则使用 [mcp] 扩展。两者提供的数据没有区别。

通过 uvx 运行（无需安装）。 可以跳过 pip install，让 uv 按需获取并运行软件包——设置 "command": "uvx"、"args": ["oxford-ledge-mcp"]。由于软件包未声明任何必需依赖，直接运行 uvx oxford-ledge-mcp 会使用内置 JSON-RPC 循环（功能完整，零额外依赖）；只有在明确需要使用该官方库处理协议时，才添加 "args": ["--with", "mcp", "oxford-ledge-mcp"]。两种方式都能连接 Claude Desktop。在 Windows 上，如果 Claude Desktop 提示服务启动失败，通常是因为它在图形界面的 PATH 中找不到 uvx——请将命令设为绝对路径 （例如 C:\\Users\\<you>\\.local\\bin\\uvx.exe）。

---

三种模式

此服务可在三种模式之一运行——请选择与 Oxford Ledge 订阅状态相匹配的模式。pip 软件包是面向用户分发的标准路径；树内开发服务仅供 Oxford Ledge 贡献者使用。

1. API 模式（推荐）——全部 29 个工具

如需完整功能，请将服务指向正在运行的 Oxford Ledge 实例。将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "oxford-ledge": {
      "command": "oxford-ledge-mcp",
      "env": {
        "OXFORD_LEDGE_URL": "https://www.oxfordledge.com",
        "OXFORD_LEDGE_API_KEY": "ol_live_..."
      }
    }
  }
}

OXFORD_LEDGE_URL 应为你有权访问的 Oxford Ledge 实例的 URL（公共应用、你自己可自托管的部署，或用于本地开发的 http://localhost:5000）。如果同时设置了 OXFORD_LEDGE_API_KEY，则除非主机是回环地址（127.0.0.1、127.x.y.z、[::1]）或字面值 localhost，否则会拒绝普通的 http:// URL——否则密钥会以明文传输。请注意，127.1 这种简写不是可解析的地址，会被拒绝；请写作 127.0.0.1。向回环主机发送携带密钥的请求时，不会使用环境中的任何 http_proxy / HTTP_PROXY，而是直接连接本地接口，因此企业代理或系统代理既看不到密钥，此设置也不需要 no_proxy 条目。请求 https:// 主机时仍会遵循环境代理设置。

OXFORD_LEDGE_API_KEY 是你的 Oxford Ledge API 密钥——登录后，在应用中进入 YOUR API KEYS → + Create Key 创建：按 K 或打开 Settings -> API keys，也可以打开 oxfordledge.com/?panel=api-keys 直接打开该面板（没有 /account 页面）。密钥会作为 x-api-key 标头发送（绝不会出现在 URL、日志行或错误消息中，也绝不会跨重定向转发），它能让这些工具成为你的工具：

• 不提供密钥时，此客户端对 API 而言是匿名的——但 29 个工具中仍有 27 个会正常响应，这是刻意设计的：4 个独立工具从不访问 Oxford Ledge；14 个通过名称代理的 ol_* / gov 工具使用托管服务的匿名 /mcp 传输；9 个 REST 代理工具调用不需要身份验证的路由。不提供密钥时，无法使用以下功能：两个 Plus 层级工具会拒绝免费层级调用者——托管服务会进行层级检查，而 wheel 会将结果转换为 AUTH_REQUIRED，说明该工具所需的层级、此客户端为匿名状态、如果操作方已有包含该层级的套餐则应设置 OXFORD_LEDGE_API_KEY（已付费订阅但未设置密钥的用户收到的正是此拒绝信息），否则说明在哪里升级；此外，只有提供密钥的调用者才能触发提供已存储行的读取（get_activist_stakes 背后的 EDGAR 刷新操作，此时会报告 stale: true）。
• 提供密钥时，工具会根据你套餐的层级进行解析，调用也会归属到你的账户（参见 /api/billing/agent-usage）。套餐层级低于 Plus 的有效密钥也会收到 AUTH_REQUIRED，但提示语会说明密钥已接受，缺少的是套餐所需层级——绝不会说“检查密钥”。试用密钥（ol_trial_...）同样有效——可在 14 天内评估付费工具，无需信用卡，但受每日上限限制。设置密钥后，9 个 REST 代理工具还会发送一个 X-OL-MCP-Tool 标头，其值为工具自身的名称（不含参数或软件包版本），因此这些查询会计入你自己的活动页面；不提供密钥时绝不会发送此标头，而且它与密钥一样，绝不会在重定向时转发。

工具描述中的“FREE”是什么意思。 无需任何套餐层级——该工具在托管通道上没有付费墙，无论是否提供密钥。它并不代表不限量：提供密钥的调用（试用密钥除外）会像其他所有提供密钥的调用一样计入你账户的 Agent API 配额。匿名调用不会计入任何账户。

参数范围。 每个声明了架构 minimum / maximum（limit、days、since_days、quarters、max_holdings）或 maxItems（ol_bdc_common_borrowers.bdc_tickers，25）的参数，都会在调用前、两种传输方式下进行验证：超出范围的数字会被拒绝为 INVALID_PARAMS，并指出参数及其边界（`limit`: 5000 is greater than the maximum of 100——这是参考库自身的提示语）；列表过长时会提示 `bdc_tickers`: [...] is too long；不会发送任何内容，也不会静默地钳制或截断参数。托管服务会以相同方式拒绝超出范围的数字（其自身处理器会将 26 个代码组成的列表截至 25 个，wheel 的架构会声明这一限制，而不是等到发现问题后才处理）。_meta.params_accepted 会回显主机收到的参数；载荷中的 completeness 块会报告实际提供的内容（恰好达到上限时，complete: null 表示无法确定——请查看 more_available_hint）。这里统一说明一次，不在每个描述中重复。

2. 独立模式 — 4 个工具，无需 Oxford Ledge 账户

少数工具无需 Oxford Ledge 实例即可使用——这些工具由直接调用的公共 API 提供支持：

{
  "mcpServers": {
    "oxford-ledge": {
      "command": "oxford-ledge-mcp",
      "env": {
        "FRED_API_KEY": "your-fred-key"
      }
    }
  }
}

这 4 个独立工具按数据来源划分：

• 2 个完全无需密钥 — get_fundamentals + get_sec_filings（直接调用 SEC EDGAR）。无需设置任何环境变量。
• 2 个需要 FRED_API_KEY — get_yield_curve 和 get_fred_data 直接调用 FRED；如果未设置密钥，则会抛出 ToolError.API_REQUIRED，并提示“Set FRED_API_KEY”。可在 fred.stlouisfed.org 获取免费密钥。（get_fred_data 仅提供美国政府／公共领域的序列；第三方版权序列——S&P、ICE BofA、Moody's、CBOE、University of Michigan——将被拒绝。）

在独立模式下调用其他 25 个工具时，它们会抛出 ToolError.API_REQUIRED，并提示设置 OXFORD_LEDGE_URL。这与 1.x / 2.0.0 版本不同，此前这些版本使用 yfinance 支持更多独立工具。该路径已在 2.0.1 中移除——原因请参阅 MIGRATING.md。

3. 开发模式 — 在 Oxford Ledge 检出目录中运行

如果你是 Oxford Ledge 的贡献者，正在开发解析器／分发器本身，请从你的检出目录直接运行 mcp_server.py：

{
  "mcpServers": {
    "oxford-ledge-dev": {
      "command": "python",
      "args": ["/abs/path/to/oxford_ledge/mcp_server.py"],
      "env": {
        "OXFORD_LEDGE_USER_TIER": "pro"
      }
    }
  }
}

开发模式下，目录内的服务器会强制执行 OXFORD_LEDGE_USER_TIER（M2 tier-gate，2026-04-24）；将其设为一个有效的层级键——free、plus、pro、professional、institutional_plus、team 或 team-member（层级排序定义在 oxford_ledge_mcp_core/registry.py::TIER_RANK 中）——即可测试受层级限制的工具。旧版显示名称 learner 和 analyst 并非层级：learner 会映射到 free（无法使用受限工具），而 analyst 则刻意不设别名（无法使用）。API 模式或独立模式不会使用此设置：API 模式使用你的 OXFORD_LEDGE_API_KEY 进行身份验证（托管远程端点仅接受密钥／Bearer，不接受会话 Cookie）；独立模式则完全没有层级。

编辑配置后，重启 Claude Desktop。你就能看到可用的工具。

---

可用工具（29）

Mode 列：S = 可独立运行（无需 OXFORD_LEDGE_URL），A = 仅 API 模式（需要 OXFORD_LEDGE_URL；只有标记为 Plus 的两项需要密钥）。截至 3.1.0，29 个工具中有 28 个属于 gov-public-data（SEC EDGAR / FRED / Treasury / FDIC / USAspending / USPTO / CFTC），第 29 个 get_value_investing_fact 由 Oxford Ledge 编写，并排除了第三方版权字段——13F / 事件数据载荷中的 CUSIP（FactSet IP）会被剔除，S&P / ICE / Moody's / CBOE 的 FRED 序列会被拒绝。每个工具的描述（tools/list 返回的内容）都是其契约：其中说明了计量单位、行结构、空结果的含义，以及哪些字段是 Oxford Ledge 推导得出，而非源数据本身提供的数值。

已移除 — 厂商 / 第三方版权数据溯源（如有需要，请固定到较旧版本）： 3.1.0（CUSIP + FINRA 归属例外）：search_bonds、get_bond_data（债券 CUSIP 属于 FactSet IP）、get_short_interest（已公布但未解决的流通股数据溯源 + FINRA 归属问题）——固定到 ==3.0.1。**固定到 ==3.0.1 并不会让两个债券工具恢复为可用工具：**FINRA 在 2026-07 对它们抓取数据的公开 TRACE 主机实施了认证限制；2026-09-13，这两个工具也在托管服务上退役（托管工具名称会返回 status: "retired"，并返回空列表 / 空价格，绝不会返回数据）。如需发现公司债券，请使用托管服务的 ol_bond_directory_screen（LQD/HYG 目录——参考数据，不含价格）；如需查看单个发行人的到期日安排，请使用此软件包中的 get_debt_maturities。 3.0.0（移除免密公开数据）：get_stock_quote、get_financials、get_balance_sheet、 get_cash_flow、get_analyst_recommendations、get_company_info、compare_stocks、 screen_stocks、get_anomaly_flags、get_options_chain、get_economic_calendar、 get_news、search_company（固定到 ==2.1.0）。2.1.0（移除 FMP）：get_company_data、 get_company_profile、get_market_indicators、get_valuation_history、 calculate_intrinsic_value、get_price_history、get_peer_comparison（固定到 ==2.0.4）。 这些工具仍可通过 Oxford Ledge 托管 MCP 服务使用。请参阅 CHANGELOG.md / MIGRATING.md。

SEC 基本面与申报文件（4 个工具）

工具	模式	描述
get_fundamentals	S	来自 SEC EDGAR companyfacts 的 XBRL 财务数据，最长涵盖 10 年（LongTermDebt，而非总债务；逐期 concepts；考虑 NCI 的权益计算阶梯；Oxford Ledge 对 EPS / 稀释后股数进行拆分基准检查，包括跨越标签缺失期的步骤；coverage[].contiguous）
get_sec_filings	S	任意表格类型中最新的 10 份 EDGAR 申报文件（可通过 filing_type 缩小范围），包含表格类型、日期、链接和时间窗口说明
get_capital_allocation	A · Plus	基于 SEC XBRL 的资本配置评分卡——最多提供 30 个财年的标签及 periods 和拆分基准 basis 区块，并提供 10 年汇总窗口；股息、净回购（扣除发行、IPO 所得款项和 SBC）、净债务变化、收购、流通股数（托管工具，名称代理；净额序列由 Oxford Ledge 推导得出）
get_debt_maturities	A · Plus	根据 10-K / 20-F 脚注生成的未来到期日阶梯，单位为百万美元，附带解析器置信度和资产负债表验证（托管工具，名称代理；仅限 EDGAR）

所有权与内部人士 — SEC（6 个工具）

工具	模式	描述
get_13f_holdings	A	单个申报人的最新 13F-HR 持仓及季度环比变化（已剥离 CUSIP；ticker 是 Oxford Ledge 的 CUSIP 对照表，title_of_class 是权威股份类别；PUT/CALL/PRN 行均有标注；fund 接受 CIK 或股票代码，包括 BRK-B 这类不同类别股份形式）
get_holders	A	前 10 大机构股东（13F-HR 普通股持仓，采用每位申报人的最新申报；结果为空时提供范围限定的 note）
get_insider_trades	A	单个发行人的 Form 4 交易——最新 20 条，包含所有代码，衍生品行均有标注；公司使用自己的 SEC ID 申报时会标注为 issuerSelfFiled（统计总额时应排除这些记录）；dateBasis 指明所提供日期的依据
ol_insider_recent_buys	A	Oxford Ledge 发行人目录中全市场范围内的公开市场内部人士买入，按时间从新到旧排列——每日内部人士筛查（Form 4；totalValue/position 为 Oxford Ledge 推导值；已排除发行人自行申报的买入）
get_activist_stakes	A	某股票代码对应的 Schedule 13D/13G 超过 5% 的受益所有人申报（已存储的行带有 stale/age_seconds；只有提供密钥的调用方才能从 EDGAR 刷新数据）
get_fails_to_deliver	A	某股票代码的 SEC 未交割结算历史（每两周更新的 CNS 文件）

公司事件与私募配售 — SEC（2 个工具）

工具	模式	描述
get_corporate_events	A	最近 20 条 8-K 项目事件（重大协议、并购、高管变动、财报发布等；eventType 为 Oxford Ledge 的项目映射；已剥离 CUSIP/评级）
ol_form_d_raises	A	SEC 季度数据集中的 Form D 私募配售申报（约滞后一个季度发布），可按行业／回溯时间范围筛选

宏观经济 — FRED / Treasury / CFTC（4 个工具）

工具	模式	描述
get_yield_curve	S	来自 FRED 的 Treasury 恒定期限收益率曲线（11 个期限，以百分比表示；数据不完整时提供各期限的 completeness）
get_fred_data	S	美国政府的 FRED 序列（GDP、UNRATE、CPI 等），包含 units/frequency；拒绝提供第三方版权序列（S&P/ICE/Moody's/CBOE/U-Michigan）
ol_treasury_debt	A	公共债务月度报表——按证券类型／类别列示未偿债务，单位为百万美元（Treasury MSPD 原文）
ol_cftc_cot	A	CFTC 交易者持仓报告——按市场列示 Managed Money（分类数据）／Leveraged Funds（TFF）持仓；market_key、market_label、mm_net 为 Oxford Ledge 定义的字段

BDC 与私募信贷 — SEC / Oxford Ledge（9 个工具）

工具	模式	描述
search_bdc_borrower	A	查询向某借款人放贷的 BDC——每笔贷款分 tranche 显示一行，为陈旧持仓者添加标签，并汇总当前持仓者；可选用 limit/offset 通过 page 块对 tranche 行分页（SEC SoI；Oxford Ledge 解析，ol-derived）
get_bdc_list	A	正在跟踪的活跃 BDC，含 totalFairValue（经仲裁——请查看 fairValueBasis 和 fairValueGap）、持仓数量和申报日期（Oxford Ledge 解析）
get_bdc_holdings	A	某个 BDC 最新申报文件中的完整投资组合：逐项列出借款人、行业、证券类型、留置权、利率、到期日、本金／成本／公允价值（USD）和估值（占本金的百分比），并提供经仲裁的总额及 fairValueGap 标签（SEC SoI；Oxford Ledge 解析）
get_bdc_borrower_mark_history	A	某借款人在每个持有其债务的 BDC 中的多季度公允价值估值历史，按季度从新到旧排列（每季度的最低／最高／按本金加权估值、持仓行数和持仓者数量；SEC SoI；Oxford Ledge 解析，ol-derived）
ol_bdc_top_borrowers	A	按活跃贷款机构数量、再按风险敞口排序，找出由最多 BDC 联合放贷的借款人——私募信贷发现入口（SEC SoI；Oxford Ledge 解析；免费）
ol_bdc_borrower_dispersion	A	某借款人的跨贷款机构定价离散度——N 家 BDC 如何分别评估同一笔贷款（用于比较的 spread_bps、估值、服务时收益率；SEC SoI；Oxford Ledge 解析；免费）
ol_bdc_common_borrowers	A	给定一组 BDC 共同持有的借款人——跨投资组合交集查询（SEC SoI；Oxford Ledge 解析；免费）
ol_bdc_mark_changes	A	一组 BDC 的季度环比估值变动，并附带明确的 coverage 块（SEC SoI；Oxford Ledge 解析）
ol_bdc_credit_quality	A	某个 BDC 的非应计贷款占比及其趋势：当确定性覆盖率低于 90%，或超过 25% 的贷款被标记为接近面值时，不提供结果（这正是容易误读的情形；coverage_state 会说明具体情况）；当超过 25% 的贷款被标记为低于 85 或档案中没有估值时，会报告该数据，但标记为 unusually_high（SEC SoI；Oxford Ledge 解析）

联邦参考数据 — FDIC / USAspending / USPTO（3 个工具）

工具	模式	描述
ol_fdic_bank	A	按名称前缀或资产规模（从高到低）查询 FDIC 承保的活跃银行和储蓄机构（FDIC BankFind；单位为 $thousands）。ticker 是 Oxford Ledge 对 CERT 与股票代码的映射，并非 FDIC 字段
ol_federal_contracts	A	按股票代码查询联邦合同义务金额，或查询财政年度排行榜（USAspending）。股票代码归属和按股票代码统计的总额来自 Oxford Ledge 交叉映射；dropped_unresolved 是其差额的上限
ol_patents	A	某股票代码对应申请人的 USPTO 最新专利申请（USPTO ODP；ticker 是 Oxford Ledge 对申请人名称的解析结果）

参考 — Oxford Ledge（1 个工具）

工具	模式	描述
get_value_investing_fact	A	来自 Oxford Ledge 精选语料的 Buffett / Graham / Munger 原则及注明出处的转述，并附有 attribution 署名行——措辞未经来源核实，因此除非 verbatim 为 true，否则不属于逐字引述（ol-authored）

---

_meta.basis 的含义

每个成功的工具响应都包含一个 _meta 块（terms_url、 source、source_url、basis，以及在负载中注明时的 as_of / period；25 个代理工具还会携带 source_key 和主机的 disclaimer——4 个独立工具则会在顶层携带“不构成建议”字面声明）。错误信封包含错误，而非 _meta。它的来源取决于工具获取数据的方式，而这三种路径使用同一套术语：

• 16 个名称代理工具（14 个无需密钥的 ol_* / gov 工具，加上两个 Plus 层级工具）会原样传递托管服务的 _meta；
• 9 个 REST 代理工具会携带托管路由的溯源中间件附加到该路由上的 _meta（与托管目录共用唯一事实来源，因此 wheel 和托管服务不会对同一负载作出不同表述）。其中两个会将路由的负载重塑为各自的键——get_holders 和 get_insider_trades——它们会在重塑时把路由的 derived_fields 路径转换为自身的键名（trades[].value，而不是路由的 transactions[].totalValue；wheel 上不会传递的路由 QoQ 路径会被舍弃；wheel 自身的 vintages / rankingBasis / transTypeLabel / is_open_market 会被添加），因此该列表可用于其所在的负载；
• 4 个独立工具（get_fundamentals、get_sec_filings、 get_yield_curve、get_fred_data）完全不会接触 Oxford Ledge，因此 wheel 会在调度环节附加自己的表——{source, source_url, terms_url, basis: primary}——并通过主仓库中的契约测试，使其术语与托管溯源注册表保持一致。

basis 告诉你读取的是谁的数据。六种取值及仅凭该字段可得出的结论如下：

value	含义	配套字段
basis: primary	所有实质性数值均原样来自所引用的 source（申报文件、机构表格、FRED 序列）	--
basis: hybrid	所引用来源的数值均原样保留，但 derived_fields 中列出的字段除外；这些字段是 Oxford Ledge 推导所得（实体归属、交叉映射求和、分类标记）。source 仍指明主要来源：需要致谢的是该来源，其他数值也可在此核验	derived_fields（使用工具自身键名的路径；[] 表示列表行，. 表示嵌套字典；路径可能只对应工具某个分支输出的键）和 derived_basis（目前始终为 ol-derived）——仅当 hybrid 时两者都存在，否则均不存在
basis: ol-derived	负载是 Oxford Ledge 基于主要输入计算得出的结果（计数、筛选结果、跨申报方联接、汇编资料）。source 指明输入来源。不要将其引用为申报方或机构自己的数据	提供模型撰写或汇编文本的工具会在负载中标注此类内容（ai_generated / descriptionSource）：这些文本并非申报文件原文
basis: ol-authored	由 Oxford Ledge 撰写（价值投资语料库、术语表、方法论）	--
basis: vendor-derived	由数据供应商计算，而非申报方或我们计算	--
basis: aggregated	跨来源汇总（新闻）	--

hybrid 的一个示例是 ol_fdic_bank：institutions[].ticker 来自我们的 CERT 到股票代码映射表；其他所有字段均来自 FDIC BankFind。工具 描述中也以文字说明了相同内容（ATTRIBUTION: ...），因为调用前， tools/list 的读者需要了解这一点；负载中的字段也会说明这一点，因为 负载是机器消费者读取的唯一渠道。

数据来源

这 29 个工具中，有 28 个基于美国政府公开数据——SEC EDGAR、FRED、U.S. Treasury、FDIC、USAspending、USPTO 或 CFTC；第 29 个工具 get_value_investing_fact 由 Oxford Ledge 编写（basis: ol-authored，包含带有归属信息的转述和原则，其措辞未经原始来源核实；每一行均带有 author / source / attribution，且只有经原始来源核实的文本才会将 verbatim 设为 true）。本软件包中的任何内容都不会抓取 Yahoo Finance（1.x / 2.0.0 中使用 yfinance 的路径已在 2.0.1 的 Y1 移除中删除），并且截至 3.0.0，整个接口中都不再有商业供应商的数据源（由 FMP/Finnhub 提供数据的报价／预估／筛选／新闻工具已移除——这些工具位于托管的 Oxford Ledge MCP 服务上）。截至 3.1.0，来源为 FINRA 的工具也已移除：债券搜索和 CUSIP 查询（search_bonds / get_bond_data）分发了受 FactSet 许可限制的 CUSIP；get_short_interest 则是一个已公布但未解决流通股数据谱系和归属问题的存根。FINRA 数据现在仅托管在服务端——其中 TRACE 部分也已从该服务端移除：FINRA 于 2026-07 对其公开 TRACE 主机设置了身份验证墙，而 Oxford Ledge 没有重新分发 TRACE 数据的许可证，因此托管的 search_bonds / get_bond_data 已于 2026-09-13 退役（它们会返回 status: "retired"，绝不会返回数据）；托管的公司债发现工具是 ol_bond_directory_screen，这是一个持久化的 LQD/HYG 目录，不含价格；托管的空头权益工具（FINRA 的双周序列）不受影响。**在 3.4.0 中，全面审计发现的一处数据泄漏已重新封堵：**从 3.1.0 到 3.3.0，get_debt_maturities 和 get_capital_allocation 会代理两个 REST 路由，这两个路由可能回退到由 Finnhub 提供数据的资本结构快照和建模的到期梯；在 3.4.0 中，这两个工具都只是托管版、仅使用 EDGAR 的工具的名称代理，因此接口再次不含供应商数据。

• SEC EDGAR — XBRL 基本面数据（get_fundamentals）和任意类型的 EDGAR 文件提交列表（get_sec_filings）由 pip 包直接从 EDGAR 获取（无需密钥）。内部人士 Form 4（get_insider_trades）、13F 持仓（get_13f_holdings / get_holders）、8-K 事件（get_corporate_events）和 BDC 投资明细表解析则通过 OXFORD_LEDGE_URL（API 模式）调用 Oxford Ledge 基于 EDGAR 的表；资本配置评分卡和债务到期阶梯是托管的 EDGAR-XBRL / 10-K 脚注工具，按名称代理调用。
• FRED / U.S. Treasury — 美国财政部收益率曲线和 FRED 系列数据均直接获取，原样提供（basis: primary，不做任何衍生处理）。需要 FRED_API_KEY（没有该密钥时，get_yield_curve / get_fred_data 会报错）。get_fred_data 仅提供美国政府 / 公有领域系列数据——第三方版权所有的系列数据（S&P、ICE BofA、Moody's、CBOE、University of Michigan）会被拒绝，且默认关闭。
• FDIC / USAspending / USPTO / CFTC — BankFind 机构记录、联邦合同义务、专利申请文件和交易商承诺报告头寸数据，全部通过 OXFORD_LEDGE_URL 路由。这四项均为 basis: hybrid，并在其描述（ATTRIBUTION: ...）和 _meta.derived_fields 中注明：ol_fdic_bank — institutions[].ticker 是我们核实过的 CERT-to-ticker 映射（一条路径）；ol_federal_contracts — ticker 归属、每个 ticker 的 total_obligations_usd 和 entity_count 总和，以及 dropped_unresolved 均来自我们的交叉映射表，涵盖 ticker 和排行榜分支（八条路径；dropped_unresolved 是交叉映射表遗漏项的上限，并非漏掉的子公司的数量）；ol_patents — filings[].ticker 是我们对申请人名称的解析（一条路径）；ol_cftc_cot — rows[].market_key 和 rows[].market_label 来自我们整理的市场目录，rows[].mm_net 是我们的 mm_long − mm_short（三条路径）。这些数据载荷中的所有其他字段均为机构提供，原样呈现。
• Oxford Ledge 专有解析 — 来自 SEC SoI 文件的 BDC 持仓（在 3.7.1 版本发布时，get_bdc_list 列出 48 家活跃 BDC；已关闭或合并的 BDC 的最终文件仍可通过借款方工具读取，并标记为非活跃）+ 精选的价值投资语料库。仅限 API 模式；其数据载荷会在 _meta.basis 中标注 ol-derived / hybrid / ol-authored，描述文字也会注明。

---

数据许可

以下 MIT 许可证涵盖本软件包中的软件。工具返回的数据受 Oxford Ledge 服务条款约束（https://www.oxfordledge.com/terms），每个负载都通过 _meta.terms_url 链接到该条款。适用条款摘录如下：

• 署名（第 5b 条）：“重述给最终用户时，必须注明由 Oxford Ledge 派生的值来自 Oxford Ledge（oxfordledge.com）。无论该值以数字、图表，还是 Agent 围绕它撰写的文字形式传达给最终用户，都适用此要求。底层公开文件（SEC EDGAR、美国财政部及类似的美国政府来源）属于公共记录，不受此要求约束；此义务仅针对我们的派生层——我们对业务发展公司投资明细表的解析、借款人规范化与贷款身份标识键、分散度与定价汇总，以及我们计算的模型输出。在本软件包中，ol-derived、hybrid（derived_fields 路径）或 ol-authored 的 _meta.basis 正是对此的标记；basis: primary 负载则是机构的公开记录。”
• 不得批量提取（第 5b 条）：“您不得使用 Agent 接口系统性地枚举、下载或重建 Oxford Ledge 语料库或其任何重要部分，以构建竞争性或替代性数据集，也不得将我们的派生值作为数据产品转售或重新分发。按查询和实体进行研究正是这些接口的用途；重建语料库则不是。”
• 个人和内部使用（第 8 条）：“通过 Oxford Ledge 获取的数据仅授权用于个人和内部用途。未经 Oxford Ledge 事先书面许可，您不得重新分发、转售、重新发布、再许可，也不得向第三方提供从服务中获取的任何数据、数据集或内容，无论其形式是原始、汇总还是派生数据。”

---

此客户端自行实施的资源限制

这些限制是客户端自身的属性，并非任何服务的属性。设置这些限制是因为桌面 MCP 客户端会将主机发送的所有内容保存在编辑器所启动进程的内存中，而且 OXFORD_LEDGE_URL 由操作方提供。

• 响应大小。 超出对应主机上限的成功响应正文会在完整读取前被拒绝：不会解析、提供或缓存任何内容，且拒绝消息会指出上限，方便您将其与服务中断区分开来。各主机的上限分别为：您配置的 Oxford Ledge 实例为 8 MB，SEC XBRL companyfacts 为 32 MB（大型申报方的文档确实可能超过 8 MB），SEC submissions 为 16 MB，SEC ticker map 为 8 MB，FRED 为 16 MB。
• 缓存大小。 工具结果会在进程内按工具的 TTL 缓存，并受两项预算限制：最多 500 个条目，且序列化负载总量最多为 32 MB。如果总量将超出字节预算，则会丢弃最早过期的条目；单个结果若大到无法纳入预算，则不会缓存，但调用仍会正常返回。缓存未命中绝不会构成错误。两项预算均以进程为单位，缓存不会在进程间共享。
• 响应嵌套深度。 嵌套深度超过约 500 层的响应会被拒绝，并说明原因，而不会提供。达到此深度后，用于防止一位调用方修改另一位调用方结果的副本机制将不再安全；真实的 Oxford Ledge 和 SEC 文档通常只有几层嵌套。

---

我们不提供的功能

get_ai_question 有意不包含在 pip 包中。 Claude Desktop 和其他所有 MCP 客户端本身都是大模型，且上下文中包含完整的用户对话。让 Oxford Ledge 生成“我接下来应该询问有关 AAPL 的什么问题？”这类问题，与使用方大模型原本就能完成的功能重复；更糟的是，我们只能看到股票代码，看不到推理过程。如果你想使用 AI 引导分析，请直接访问 www.oxfordledge.com 使用 Oxford Ledge 应用，在那里，RAG 上下文和用户会话可以提供真正实用的建议。决策记录请参阅主仓库中的 docs/reference/KNOWN_GAPS.md。

---

完整平台

如需体验完整功能，包括 45+ 个数据库、新闻档案、信用分析、BDC 数据和 AI 驱动的分析，请访问 www.oxfordledge.com。

---

免责声明

Oxford Ledge 是面向终身学习者和投资者的研究与教育平台。本软件按“原样”提供，不附带任何形式的保证，并依据 MIT License 授权（参见 LICENSE）。它是一个用于访问和解析公开金融数据的 MCP 服务。它不构成投资、金融、法律或税务建议，其返回的任何内容都不是买入、卖出或持有任何证券的建议。 数据可能不完整、存在延迟或不准确——SEC 文件定期提交且有滞后，FRED 序列也会修订。你有责任独立核实所依赖的任何信息，并对自己的投资决策负责。完整条款：https://www.oxfordledge.com/terms

---

许可证

MIT（软件）。数据单独授权——请参阅上文的数据许可。

验证安装

重新启动 MCP 客户端后，检查服务握手：连接时，客户端会显示服务名称 oxford-ledge-mcp <version>（在 Claude Desktop 中：Settings → Developer → oxford-ledge）。如果显示的版本低于你安装的版本，说明客户端仍在运行先前的安装版本——请参阅下方第一条故障排除说明。

故障排除

实际使用中遇到的问题，以及相应的解决方法：

• pip install --upgrade 因 WinError 32（文件正在使用）失败 — 正在运行的 MCP 服务进程占用了 oxford-ledge-mcp.exe。完全退出 MCP 客户端（Claude Desktop），或终止 oxford-ledge-mcp 进程，然后重新运行升级命令。
• site-packages 中出现 ~xford-ledge-mcp 目录 — 这是升级中断后留下的残余文件（即上文的 WinError 32 情况）。升级成功后可以安全删除。
• 安装后找不到 oxford-ledge-mcp — pip 在安装期间打印了 PATH 警告。可以将提示中给出的 Scripts 目录添加到 PATH，或者在客户端配置的 command 字段中填写可执行文件的完整路径。
• 握手显示旧版本 — 客户端缓存了旧进程。完全退出客户端并重新启动。使用 uvx 的用户：uvx 环境缓存可能会固定旧版本——请刷新缓存（uvx --refresh oxford-ledge-mcp），或明确指定版本。
• 工具返回 NOT_FOUND: unknown tool — 你安装的软件包版本可能比托管服务新，反之亦然（版本不匹配）。将握手显示的版本与本 README 中的版本进行比较，并升级较旧的一方。