Canary MCP

Canary

为你的经纪账户提供本地风险台。

目前可通过 IB Gateway 或 TWS 运行，并将经纪商层封装在独立的 Go 包 pkg/ibkr 中，以便后续支持其他经纪商。

Canary 将一个本地 IB Gateway 或 TWS 会话转化为每日简报、当前投资组合和市场证据，以及经纪商确认的过往持仓变更成效回顾。你可以从 MCP 宿主、Shell 或配对手机使用同一个守护进程。标准二进制文件无法下单、修改订单或取消订单；它可以预览订单，此操作会向网关请求假设情景检查，不会创建订单。任何构建版本中的 MCP 工具都无法预览或执行订单。

Canary 面向在本地运行 Gateway 或 TWS、并希望持续看到过时、缺失或暂缓的证据的 IBKR Pro 用户。它不是托管式经纪服务、交易推荐工具，也不是完整的 TWS API 替代品。如果你只需要 Go 线协议客户端，请使用 pkg/ibkr。如需从自己的 Go 程序读取正在运行的 Canary，请导入模块根路径 github.com/osauer/canary/v2：它会通过守护进程套接字运行同一只读工具目录，而 canarytest 会在临时套接字上提供线协议类型供测试使用。客户端还提供范围有限且经过审计的现金扫款下单偏好设置；其工具目录仍为只读，且该偏好设置无法启用储备资金或经纪商执行功能。

文档 · 安装 · 首次会话 · Canary Edge · MCP 工具 · 安全 · 隐私

开始使用

你需要 IB Gateway 10.37+ 或启用了 API 套接字访问权限的 TWS、IBKR Pro 账户，以及运行于 arm64 或 amd64 架构的 macOS 或 Linux。WSL 可用；原生 Windows 不可用。

如需让 Shell 和本地 MCP 宿主共用一个二进制文件：

curl -fsSL https://raw.githubusercontent.com/osauer/canary/main/install.sh | sh
canary status    # prove which gateway and account Canary reached
canary brief     # review what changed and what needs attention

安装程序会验证已签名的发行版校验和，并安装到 ~/.local/bin。安装指南介绍了如何先检查脚本，并涵盖其他所有安装方式。Canary 可以自动发现 Gateway 或 TWS；canary status 会显示所选连接和账户。明确指定的端点会保持固定。市场数据的可用性取决于你的 IBKR 订阅：延迟数据会继续标注为延迟数据，不能满足仅限实时数据的执行要求。

仅适用于 Claude Desktop：下载 canary.mcpb， 用 Claude Desktop 打开，然后完全退出 Claude 并重新启动。你可以询问：

今天有哪些事项需要关注？哪些输入数据已降级？

该安装包自带 macOS 和 Linux 二进制文件。Claude Desktop 使用指南介绍了首次连接的步骤。

当前 Canary SPA 使用合成数据渲染。Edge 展示已观察到的历史结果，并非预测，也不代表因果关系。

选择你的使用方式

你想要……	从这里开始	边界
向 Agent 询问账户相关信息	MCP Bundle，或通过任何能够启动 stdio MCP 服务的本地框架运行 canary mcp	只读工具；不包含设置写入、预览或执行工具
在终端或脚本中工作	canary brief、canary positions --by underlying 和 --json	通过同一守护进程权限提供确定性的 CLI 输出
用手机查看交易台	canary app，然后运行 canary app pair	配对后的 PWA；默认在本地运行，可选远程中继
在自己的 Go 程序中读取 Canary	github.com/osauer/canary/v2 守护进程客户端，以及用于测试的 canarytest	通过守护进程套接字访问 MCP 工具目录，无需启动 MCP 进程；守护进程保留所有策略和经纪商限制
直接基于 TWS 协议构建	github.com/osauer/canary/v2/pkg/ibkr	更底层的传输；策略、授权和日志记录由你的应用负责

受限制的经纪商操作不是第五种入门方式。它们需要单独的实验性交易二进制文件，且仍仅限于受限制的 CLI 和配对应用工作流。任何构建版本中的 MCP 始终为只读。在使用该构建产物前，请阅读 受限订单与交易构建版本。

Canary 可以帮你解答的问题

• 现在有哪些事项需要关注？ canary brief、Rulebook 和 Action Queue 会汇总当前警报、流程例外、保护候选项和操作候选项，但不会因此赋予任何行下单权限。
• 我是否在限额范围内？ canary rules 会根据持仓规模、权利金预算、时间价值、到期日、亏损、净市场敞口和保证金余量检查账簿。这些规则以编译后的基线为起点；canary rules policy set 可将其设为你的规则。
• 账簿的敞口情况如何？ 账户和持仓读取会选定一个账户，按标的分组显示股票和期权腿，并将缺失值与实际的零值区分开来。每个持仓都会标明 IBKR 报告的上市交易场所。若账户不止一个且无法确定所指账户，系统会拒绝合并数据。
• 过去的决策实际带来了什么结果？ Canary Edge 使用留存的 IBKR Flex 记录和精确合约的市场历史数据。在确认外部资金流后检查账户损益；将股票和 ETF 中有足够重复样本的开仓、加仓、减仓和平仓，与保持此前持仓不变的情况进行比较，涵盖 1、5 和 20 个交易日；并单独报告经纪商记录的期权损益。它不会推断意图、推荐交易，也不会声称存在因果关系。
• 股票出借赚取了多少？ 带日期的出借股数标注和 canary lending fees --json 可提供客户净费用、可展开的历史记录以及明确的报告覆盖范围。参与与否由 IBKR 控制。费用用于说明收入；绝不会再次计入经纪商账户损益。付款关联关系尚未得到证实。请参阅出借报告。
• 有哪些高费率标的在我的列表之外？ canary lending screen --min-rate 50 --limit 25 --json 和 MCP canary_lending_screen 会对现有的 IBKR 美国股票、美元批量数据源进行排序。可选的排除项可移除常见标的；覆盖范围、数据源日期和截断情况均会明确说明。这不能证明上市质量、流动性或出借方收益率。
• 哪些美国股票有大量报告的空头持仓？ canary short-interest screen --listed-only --min-average-volume 1000000 --json 会先按 FINRA 空头股数排序，再限制结果数量。可按 days_to_cover 排序，或添加通用价格／流动性筛选条件；市场覆盖范围会明确说明，流通股比例仍不可用。请参阅数据源与新鲜度语义。
• 哪些标的的借券费率异常高？ canary lending rates --symbols AAA,BBB --json 和 MCP canary_lending_rates 会读取明确指定的美国股票范围内、带日期的参考借券成本。保留缺失数据、数据源时效和数值尺度。这些费率是研究输入，不代表你的出借收益率，也不是买入建议。请参阅出借研究。
• 汇率贡献了多少？ canary reporting fx --json 会读取投资、外币现金和应计利息的已完成每日估值影响，并保留缺失的日期。这不同于 IBKR Forex P/L Details 中已实现的货币批次损益。请参阅外汇报告。
• 这份数据可信可靠吗？ 报价、日历、市场广度、Gamma、市场状态、压力、财报、借券、停牌和报告数据源各自提供健康状态、新鲜度、覆盖范围及最近一次正常状态。不可用的证据仍会标记为不可用。canary data health --json 会读取服务报告；canary data check --json 会发起有界的常规报价检查。服务健康并不意味着每个报价都是实时的或适合执行交易。
• 市场何时开市？有哪些日程安排？ 交易所日历涵盖美国股票和上市期权、Xetra、伦敦、东京和香港，并明确标注覆盖范围边界和盘中休市时段。canary macro 会单独读取缓存的官方经济日历和公告，并显示其数据源健康状态。
• 下单前能否先审核加仓方案？ canary add plan 会检查股票加仓；canary add preview 会审核确切条款，包括是否为新增股份设置止损。canary add market 会查找看涨期权，canary add call-plan 会根据预算为确切的看涨期权确定规模。这些命令不会下单。请求示例和独立的确认边界，请参阅加仓命令指南。
• 如何在保留指定持仓的同时降低敞口？ canary locks 会将指定行排除在批量和自动减仓之外。投资组合减仓可针对净敞口、多头持仓、行业或较高 Beta 持仓。--plan 会显示拟议的减仓方案，但不会创建任何可供提交的内容。直接针对单个持仓的减仓仍可作用于已锁定的行。请参阅减仓与持仓锁定。
• 已有哪些工作？ 提案、机会和本地订单日志会显示哪些事项受阻或已准备好供人工审核，以及它们发生了哪些变化。它们是证据，不具有经纪商权限。多腿期权持仓会作为一个整体进行审核：使用最新的腿报价，将已付净权利金与净平仓价值进行比较，然后交由策略工作流或经纪商组合订单处理；该行本身不会下单。期权用途依据测得的账簿情况，而非逐腿声明。可选择启用的现金扫入功能会建议将闲置现金投入相同币种的国库券；它绝不会将一种货币兑换为另一种货币。 对账、基于对账单的权益以及 Edge 需要共用一个 IBKR Activity Flex Query。运行 canary setup reporting，然后按照 截图指引字段清单操作。收到的空 部分视为报告活动为零，不会阻碍就绪状态。 缺少部分与已填充行中缺少必填字段是不同的问题；canary reporting status --json 会显示当前证据。

MCP 和 Agent 框架

MCP Bundle 是配置 Claude Desktop 最快捷的方式。对于其他本地宿主， 请安装共享二进制文件，并将宿主指向其绝对路径。使用通用 mcpServers 结构的宿主可以接受：

{
  "mcpServers": {
    "canary": {
      "command": "/ABSOLUTE/PATH/TO/canary",
      "args": ["mcp"]
    }
  }
}

使用 which canary 查找路径。仅限浏览器的 Agent 无法访问此本地 stdio 进程。升级后，请完全重启宿主，使其重新启动 MCP 服务。

持续运行的 Agent 可以让此 MCP 子进程保持可用，并重复使用 Canary 的简报、日历、市场状态、风险和订单证据。使用 canary_calendar 获取官方交易所交易时段，使用 canary_macro 获取官方经济日历和公告，并使用 canary_data_health 获取被动式数据源健康状况。保留其覆盖范围边界和原始数据源时间。宿主负责持久唤醒、模型预算和进程恢复。Canary 负责观测结果和风险语义。有关生命周期和数据质量约定，请参阅 持续运行的宿主。

使用交易台上的说法提问，而不是直接说出工具名称：

我的投资组合按标的资产划分的敞口情况如何？

哪些重复建仓、加仓、减仓或平仓的观测到的 20 个交易日价格影响最大？该答案的覆盖范围是什么？

是否有任何保护或行权候选项已准备好供人工审核？

宿主指南涵盖 Claude Code、Cursor、Continue、 Zed、框架集成、日志和连接检查。生成的 MCP 参考列出了准确的工具和架构清单。可选的 Claude Code 插件提供 Canary 的技能、MCP 配置和安全钩子；它不包含二进制文件。

Shell 和配对应用

每条数据命令都支持 --json：

canary data health
canary account
canary positions --by underlying
canary brief
canary edge
canary rules
canary regime --explain
canary stress --details
canary technical SPY,QQQ
canary calendar --market us --days 14
canary macro
canary market
canary reporting status
canary proposals list
canary opportunities list
canary orders open

如需持续显示，canary market --watch --json 会以明确的账户范围和独立的数据源时钟流式传输经纪商更新。单日图表会保留周末和休市期间最后一个适用的交易时段；保留的柱线会沿用其实际日期。

遇到连接问题时，先运行 canary status；对于缺失或降级的输入，运行 canary data health。完整的命令和标志清单见 canary --help 和 CLI 参考。

如需使用配对应用，请在拥有 Gateway 或 TWS 会话的机器上运行 canary app，然后运行 canary app pair 并扫描二维码。当前工作区包含 Monitor、Positions、Edge、Alerts 和 Orders；可通过标题栏的齿轮图标打开 Settings。有关本地配对、远程中继和 Web Push 的边界，请参阅应用指南。

Go wire-protocol 库

pkg/ibkr 是一个基于清洁室实现的 TWS wire protocol Go 客户端：

import (
    "context"
    "time"

    "github.com/osauer/canary/v2/pkg/ibkr"
)

func accountSummary(ctx context.Context, clientID int) (*ibkr.RawAccountSummary, error) {
    cfg := ibkr.DefaultConfig()
    cfg.Port = 4002 // Gateway paper

    connector := ibkr.NewConnector(&ibkr.ConnectorConfig{
        // Use an ID not already owned by Canary or another TWS client.
        PreferredClientID: clientID,
        BaseConfig:        cfg,
    })
    if err := connector.Start(ctx); err != nil {
        return nil, err
    }
    defer connector.Stop()

    return connector.RequestAccountSummary(ctx, 5*time.Second)
}

协议覆盖范围以用途为导向，并非面面俱到。该包负责传输经纪商请求，但不提供 Canary 在应用层面的权限边界。直接使用该包的用户必须自行提供策略、授权、日志记录和对账控制。请从包文档开始。

公共 Go 模块有意继续维护 /v2 版本线，而产品 v3 则以签名二进制文件的形式发布。因此，go install github.com/osauer/canary/v2/cmd/canary@latest 安装的是 v2 CLI，而不是产品 v3。

一个权威源，多个适配器

shell, MCP host, or paired app
              ↓ local Unix socket
         canary daemon
              ↓ local TCP by default
       IB Gateway or TWS

守护进程按需启动，负责管理所选账户、经纪商连接、市场证据、策略状态和本地订单日志，并通常会在空闲 15 分钟后退出。适配器负责呈现守护进程返回的类型化结果；它们不会重新实现风险策略。官方公共数据源也会向守护进程提供数据；即使未连接经纪商，内置交易所日历仍可使用。 架构 和存储指南介绍了这些边界，以及为确保升级连续性而保留的 ibkr XDG 路径。

安全与隐私

• 只读是产品的默认模式。 安装程序、更新程序和 MCP Bundle 均会选择标准二进制文件，该文件编译时不包含经纪商写入路径。其 CLI 仍可预览订单；预览不会创建订单，并且此构建版本会拒绝下单。
• 所有构建版本中的 MCP 均不提供预览或执行工具。 它无法下单、修改、取消、提交或行权。
• 交易是单独的决策。 实验性交易构件会将操作限制在以下条件之下：固定且经经纪商确认的账户、固定的客户端 ID 和交易模式、任何明确固定的端点、新鲜且精确的审核契约、适用情况下的经纪商资格、健康的日志记录、守护进程重新验证、运行时冻结，以及针对具体交易的人类授权。
• 缺失的证据仍然缺失。 输入过期或不可用时，不会仅因存在旧值就变成干净的结果。

Canary 不收集遥测数据，也不会向维护者发送账户 ID、余额、数量或盈亏。已配置的公共数据刷新、MCP 主机、远程中继或推送服务，只会接收你启用的路径所披露的数据。 PRIVACY.md 是权威的数据说明；SECURITY.md 介绍威胁模型和签名发布构件。

帮助与项目信息

• 安装与首次运行
• 日常工作台工作流
• 故障排除
• 配置
• 发布与更新策略
• 参与贡献

Canary 是一款独立的第三方客户端，用于 Interactive Brokers 公开文档所述的 TWS API。它并非由 Interactive Brokers Group, Inc. 或其关联公司构建、认可、赞助或支持。pkg/ibkr 不会再分发任何 Interactive Brokers 代码、库、jar 文件或市场数据。本文内容不构成投资建议。

Canary 是 Oliver Sauer 的个人项目。

MIT。请参阅 LICENSE。

可通过 canary reporting fx 和只读的 canary_reporting_fx MCP 工具参与 FX 贡献。有关每日证据、对账、查询字段以及 Day/Week/Month/YTD 语义，请参阅 FX 贡献与回填。

借贷价格和流动性背景

canary lending market --symbols AAA,BBB --json 和只读的 canary_lending_market MCP 工具会返回匹配的缓存背景，适用于借贷行情源中 1–100 个明确指定的 USD 名称，或已为显示的研究行解析出的精确标的。 按名称读取不会启动缺失行情源的解析； 如果两种标识都没有，该行仍不可用。 守护进程每个研究类别最多接纳 150 个尚未尝试的后台名称，之后会在后续读取时 逐步接纳更多名称。单个合并工作线程会轮换类别，并在后台通道上逐个刷新名称 （上限 35 秒）。 只要仍有请求，最多保留 30,000 个精确合约的投影数据；无关注 24 小时后过期。 按名称读取会请求 15 分钟的报价；日内收据 5 分钟后过期。已完成交易时段的 历史数据会重复使用，直至下一个已完成交易时段，并保留其实际来源日期。不完整 的历史数据每小时重试；失败后 5 分钟重试，但 IBKR 不认可为合约的名称会显示为 不可用，并至少等待 30 分钟，且须等到经纪商交易时段发生变化。历史数据使用 持久化缓存，不会新增图表刷新关注项。筛选读取时不会扇出请求报价。

各行包含最近已完成收盘价或近期实际成交价（包括延迟行情标签）、相对前收盘价 的变动、交易时段成交量、过去全部 20 个已完成交易时段的日均美元成交额，以及 基于上一年末精确交易时段的已完成收盘价计算的年初至今价格变动。年初至今数据 不含股息；缺少年末、最近交易时段或任何成交量基准时，相应数据保持缺失。字段 日期以及待处理、部分可用、不可用和过期状态均会明确标示。筛选条件是研究偏好， 并非交易策略，也不保证流动性。发现筛选会先应用于完整的合格费率／排除范围， 再应用输出上限，且仅使用已知市场值。数据获取是渐进式的：解读空结果或部分 结果前，请先检查 coverage。covered、pending 和 unavailable 会对所有 候选项进行划分；complete 则要求每个候选项都具备查询所需字段（默认为价格和 成交额）。缺少年初至今数据不会影响仅按价格筛选。Desk 自有列表视图保留其独立的 指定费率／本地筛选路径，以免悄然丢弃非批量证据。

规范发现筛选和排序

canary lending screen --min-rate 50 --min-price 5 --min-avg-dollar-volume-20d 10000000 --min-high-dates 3 --sort-by avg_dollar_volume_20d --sort-dir desc --limit 50 --json

CLI 标志直接映射到 MCP/RPC 的 min_price、min_avg_dollar_volume_20d、 min_high_dates、sort_by 和 sort_dir。每个可选筛选项设为零即禁用。 排序键为 symbol、price、day_change_pct、volume、 avg_dollar_volume_20d、ytd_change_pct、fee_rate 和 high_dates。 无论排序方向如何，缺失的数值都排在最后；并列时按名称排序。 high_dates 是七个 UTC 来源日期内，费率达到或超过 min_rate 的不同来源日期数； 之后出现更低或未知的观测值时会重置计数。同一日期内先下跌后回升，会从该日期 重新开始连续计数。 每行还会公开最多七条带日期的 history 样本，用于费率图表。 重复轮询同一时间戳不会增加日期。此历史记录会与守护进程的借贷费率来源状态一同 持久化；它从实际保留的观测值开始，而非假定存在回填数据。因此，较早安装的版本 起初只知道一个日期。

显示的研究价格

返回的发现结果按显示顺序获得有限优先级： 每类最多处理 100 个名称，并包含按来源排名的发现结果尾部，因此筛选器 不会取消尚未解决的候选项；15 分钟后，未完成的任务会由下一次查询替代。 三个前台任务轮流与一个可用的后台任务交替运行，同时保留更广泛范围的处理进度。 即使 150 个名称的后台批次已满，新显示的名称仍可加入；切换标签页不会累积尚未解决的任务。

借券文件中缺失的已显示卖空兴趣标的符号，可通过一次与会话绑定的 IBKR 合约详情请求进行解析。 只有唯一且完全匹配的符号、正数合约 ID、USD 股票类型以及受支持的美国日历符合条件。 不会转换后缀、猜测普通股替代项，也不会按发行人名称匹配。 未显示且无法匹配的名称仍不可用；完整的 FINRA 范围不会触发合约解析扫描。

简短的每日历史记录读取会先提供带日期的最近一个已完成交易日收盘价；随后，一年期历史记录会补充剩余的流动性和年初至今背景信息。带日期的常规收盘价也可由规范报价提供。 没有日期的前收盘价报价和较早的最新成交价不会被赋予虚构的当前日期。 缺失或失败的年度历史记录不会影响匹配的已完成交易日价格和具有独立日期的字段。 借券费率保持独立：解析出价格并不会生成费率报价。