Finra Fixed Income

@pipeworx/finra-fixed-income

FINRA 固定收益 MCP — 美国债券市场活动汇总：美国国债交易量、公司债与机构债市场广度和情绪、证券化产品定价和交易活动，以及设有上限的交易量序列。使用平台密钥（免费的 FINRA Public 凭证）；支持自带凭证（BYO）。

属于 Pipeworx — 一个将 AI Agent 连接到 1879+ 个实时数据源的 MCP 网关。这是独立的非官方集成，与上游提供方无关联，未获其认可，也非由其发布。

工具

• finra_fixed_income_datasets() — 列出 21 个数据集键、各序列衡量的内容，以及用于筛选的日期字段。无需密钥。
• finra_fixed_income_series({ dataset, start_date?, end_date?, limit? }) — 获取一个序列。不指定日期范围时，会返回 FINRA 最新发布的周期；指定 start_date/end_date 时，会返回该时间段的数据。 美国国债数据集还接受 product_category（例如 "Nominal Coupons"）和 benchmark（例如 "On-the-run"）行筛选器，并在 totals_across_returned_rows 中返回按类别和基准汇总的交易量。

范围

仅提供汇总市场统计数据。 此工具包不会返回单笔债券交易。 TRACE 交易明细是 FINRA 的另一项产品，根据下文条款第 8 条不在范围内，并依据 FINRA Rule 7730 规定收取费用，且强制延迟六至十八个月报告。此处不提供该数据， 请求也不会获得该数据。

定价 — 根据许可，费用为零

每次调用在所有套餐中均收取 0 个积分，且不计入按用量定价的阶梯。此举并非促销活动或定价决策。 FINRA 的固定收益数据特定条款 §2.3(b) 仅允许在“未对固定收益数据收取额外或增量费用”时重新分发，因此，对此工具包收费会违反许可。工具包设置了 meter: { credits: 0 }，并且网关工具包条目设置了 zeroRated: true — 两者缺一不可，因为根据 pricing-v2，即使调用费用为 0，仍属于计入阶梯的请求，会推进客户的月度阶梯，进而改变其下一次调用的费用。

同一条款的另外两项条件也已在响应和我们发布的条款中满足：注明来源（每个响应都包含一个 attribution 字段，注明 FINRA 为所有者和来源），以及调用方不得进一步重新分发（https://pipeworx.io/terms §6）。调用方可以将这些数据用于非商业性的个人或专业用途，但不得重新分发。

身份验证

通过网关使用平台密钥（PLATFORM_FINRA_KEY），或自带凭证（BYO）。

OAuth2 client_credentials。密钥格式为 "<clientId>:<clientSecret>" — 将 Client ID 和 Client Secret 用冒号连接，这与 epo-ops 和 euipo 使用的约定相同。根据 https://developer.finra.org/fees，在 https://developer.finra.org 注册的免费 Individual / Public 凭证可使用整个 Fixed Income 组，月费为 $0。

激活须知

FINRA 凭证在激活前无法使用：注册后会获得 FINRA Gateway UserID，必须在 API Console 中接受 API Terms of Service，并通过电子邮件中的链接设置密钥；该链接会在24 小时后过期（Client ID 会通过另一封电子邮件发送）。未激活的凭证会在令牌交换时返回 401 错误，看起来像是密码错误，而非注册流程尚未完成。

注册本身需要通过人工网页流程完成 — developer.finra.org/create-account 受 JavaScript 机器人验证保护，没有 HTTP 接口。

已知缺口

treasuryWeeklyAggregates 未公开。该名称可解析，数据集也会发布字段元数据，但使用我们的凭据时，无论尝试哪个时间窗口，它都返回零行——包括 2021-01 到 2021-03，这正是 FINRA 自己的文档用作示例的范围。与其宣传一个永远无法返回结果的键，不如将它排除，并在源代码中注明。每日和每月 Treasury 汇总数据集都能正常使用。

注意事项

• 令牌主机是 ews.fip.finra.org，而不是 ews.finra.org。 后者是凭据自助服务主机，访问令牌路径时会返回一个空正文的 HTTP 500，完全看不出只是主机地址有误。
• 无法从目录页面推导数据集名称。 https://developer.finra.org/catalog 上的锚点 slug（corporate_debt_market_sentiment）无法按任何规则转换为 API 名称：实际名称是 corporateMarketSentiment——其中省略了 “Debt”。同样，“Securitized Products Trading Activity” 的实际名称是 securitizedProductTradingActivity（“Product”为单数），“Corporate And Agency Capped Volume” 的实际名称是 corporatesAndAgenciesCappedVolume（两者均为复数）。实际名称列在 https://developer.finra.org/docs 的请求示例中。名称错误时会返回一个带有该数据集名称的 404，因此看起来像是数据集不存在，而不是名称拼写错误。
• 没有分组列表。 GET /data/group/FixedIncomeMarket 和 GET /metadata/group/FixedIncomeMarket 都会返回 404。但 GET /metadata/group/FixedIncomeMarket/name/<dataset> 无需密钥，可用作名称查询接口：404 表示没有该数据集，200 表示该数据集存在且会发布字段元数据，400 表示该数据集存在但不发布字段元数据。
• 每个数据集都有自己的日期字段——使用的字段包括 tradeDate、tradeReportDate、reportDate、beginningOfWeekDate 和 beginningOfTheMonthDate，并没有通用字段。按错误字段筛选会直接返回 400（“The following fields are not available in this dataset”）。工具包的 DATASETS 映射中的每个条目都包含对应字段；finra_fixed_income_datasets 会将其作为 date_field 返回。
• FINRA 的默认行顺序为升序，而 sortFields 无法绕过这一限制。 平台仅允许在请求中对每个分区字段都携带一个类型为 EQUAL 的 compareFilters 条目时使用 sortFields——而对于这些数据集，分区字段就是日期，因此无法通过排序实现“最新优先”。如果不加处理，工具会用 2023 年的行回答“公司债券市场的交易情况如何”，而且看起来完全正常。该工具包会读取 GET /partitions/group/FixedIncomeMarket/name/<ds>（需要凭据），取最新的分区值，并通过 EQUAL 筛选器将查询限定在该分区。定价数据集（TBA、ARM/混合型、指定池、CMO、CMBS、CBO/CDO/CLO、证券化活动）既不发布元数据，也不发布分区，因此无法限定分区——这些数据集会退回到最近 180 天的时间范围，足以获取其当前数据。order 字段会说明调用实际采用了哪种路径，包括所有路径均无效、返回的行确实是存档中最早数据的情况。
• 没有可返回内容的数据集会以 200 响应并返回完全空的正文，而不是 []。将其解析为 JSON 会抛出“Unexpected end of JSON input”，看起来像是我们出了问题，而不是“没有行”——treasuryWeeklyAggregates 在未筛选的请求中就是如此。
• 这些序列会延迟发布，因此非常近期的日期范围可能确实为空，并非查询有误。

数据源

• 令牌：https://ews.fip.finra.org/fip/rest/ews/oauth2/access_token
• 数据：https://api.finra.org/data/group/FixedIncomeMarket/name/<dataset>
• 元数据（无需密钥）：https://api.finra.org/metadata/group/FixedIncomeMarket/name/<dataset>
• 分区（需要凭据）：https://api.finra.org/partitions/group/FixedIncomeMarket/name/<dataset>
• 目录：https://developer.finra.org/catalog
• 许可：https://developer.finra.org/specific-terms-fixed-income-data

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "finra-fixed-income": {
      "url": "https://gateway.pipeworx.io/finra-fixed-income/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/finra-fixed-income/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall，以及网关范围内的其他工具。因此，你看到的工具数量会多于表格中的数量：目前，单个工具包端点除了该工具包自身的工具外，还会列出大约 30 个共享工具。连接的 initialize 响应会说明确切的范围，并且是当天适用情况的权威答案。

这是有意为之，并非意外的多路复用。元工具让范围受限的连接能够回答此工具包未涵盖的问题——通过 ask_pipeworx 跨整个目录进行路由——因此你无需再添加第二个 MCP 服务。目前无法挂载不含这些元工具的工具包端点；如果额外的架构定义所占用的上下文超过路由带来的价值，请连接一次完整网关，而不是连接多个工具包端点。

也可以连接完整的 Pipeworx 网关，直接列出每个工具包的工具，而不仅仅是当前工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都会连接到同一个网关和相同的 1879+ 个数据源。唯一的区别是哪些工具包的工具会被直接列出；通过任一端点上的 ask_pipeworx 都能访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/finra_fixed_income_datasets \
  -H 'Content-Type: application/json' \
  -d '{}'

首次调用无需账户。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/finra_fixed_income_datasets。查找工具包：使用 {"query":"..."} 调用 POST https://gateway.pipeworx.io/v1/tools/search_packs。

独立运行（无需网关账户）

此软件包也可作为本地 stdio MCP 服务运行，无需 Pipeworx 账户，也无需往返网关：

{
  "mcpServers": {
    "finra-fixed-income": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-finra-fixed-income"]
    }
  }
}

或者直接运行它，以确认服务能够启动：

npx -y @pipeworx/mcp-finra-fixed-income

它通过 stdin/stdout 使用 MCP 通信，并针对仅限此工具包的工具响应 initialize/tools/list/tools/call——不包含上述网关连接提供的共享元工具。数据源和工具相同，但不支持 ask_pipeworx 路由。

使用 ask_pipeworx

你可以用通俗的语言提问，而不是直接调用工具——此功能既适用于上面的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Finra Fixed Income data" })

网关会自动选择合适的工具并填入参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT