内容
# Canary - IBKR MCP 服务器，用于 TWS 和 IB Gateway
[](https://github.com/osauer/canary/actions/workflows/ci.yml)
[](https://github.com/osauer/canary/releases/latest)
[](go.mod)
[](https://pkg.go.dev/github.com/osauer/canary/v2)
[](LICENSE)
**[文档](https://osauer.dev/canary/docs/)** · [MCP 工具](docs/docs/reference/mcp-tools.md) · [MCP 资源](docs/docs/reference/mcp-resources.md) · [配置](docs/docs/reference/config.md) · [传感器](docs/docs/understand/sensors.md) · [规则手册](internal-docs/design/trading-rulebook.md) · [交易政策](docs/docs/understand/policy.md) · [存储](docs/docs/internals/storage.md) · [架构](docs/docs/internals/architecture.md) · [平台设置](internal-docs/design/platform-settings.md) · [使用代理](docs/docs/operate/agents.md) · [移动应用](web/app/README.md)
**一个本地命令行、MCP 服务器和风险桌面，用于 Interactive Brokers.**
`canary` 将您的本地 IB Gateway 或 TWS 会话转换为结构化的账户和市场上下文，供终端、Claude Desktop、Claude Code、Cursor、Continue、Zed 和其他 MCP 主机使用。它是本地 `canary mcp` TWS 桥，用于投资组合审查、风险敞口映射、期权诊断、市场状态检查、扫描器驱动的研究、观察列表监控和仓位规模数学。
对于 MCP 用户，`canary mcp` 公开与命令行相同的类型化读取。捆绑的 MCP 接口不能放置、修改、取消或传输经纪人订单；它可以分析订单簿、规模计划和草拟预览仅限股票/ETF 限价订单。
从 shell 使用：
```sh
canary status
canary positions --by underlying
canary regime
canary stress
canary market-events --symbol GME --json
canary watch IBM --add
canary watch
canary calendar --market us --date 2026-05-25
canary quote SPY --watch
canary size --symbol AAPL --entry 207.50 --stop 202.50 --risk-pct 1
canary settings show
```
或将其连接到 Claude Desktop、Claude Code、Cursor、Continue、Zed 或任何 MCP 主机并询问：
> "我的 IBKR 账户里有什么？"
>
> "查看我的投资组合并排名我今天应该关注的风险。"
>
> "显示我的 AAPL 风险敞口，包括期权 delta。"
>
> "今天的市场状态如何？"
>
> "我应该持有、观察、降低杠杆还是清算风险？"
>
> "Xetra 在 Whit Monday 开放吗？"
>
> "如果我以 418 买入 100 MSFT，止损在 408，欧元风险是多少？"
您的账户数据保留在运行 IB Gateway 或 TWS 的机器上，除非您选择将其发送到 MCP 主机。该项目作为一个 Go 二进制文件提供，带有 CLI、本地 MCP 服务器和 Go 库。不需要 Python 运行时、Java 运行时或托管服务。
**内容** — [安装](#安装) · [您获得的内容](#您获得的内容) · [选择您的路径](#选择您的路径) · [工作原理](#工作原理) · [配置](#配置) · [安全性](#安全性) · [其他安装路径](#其他安装路径) · [故障排除](#故障排除)
## 安装
**先决条件。** 在同一台机器上运行 [IB Gateway](https://www.interactivebrokers.com/en/trading/ibgateway-stable.php) 10.37+ 或 TWS（模拟或真实）。自动发现四个标准端口上的 IB Gateway。**IBKR Pro** 账户（IBKR Lite 无法使用 TWS API）。
### Claude Desktop
下载最新的 MCP 包：
<https://github.com/osauer/canary/releases/latest/download/canary.mcpb>
使用 Claude Desktop 打开 `.mcpb` 文件，将其拖入 Claude Desktop，或使用设置 -> 扩展 -> 高级设置 -> 安装扩展。完全退出 Claude 后，请重新启动它。
MCPB 捆绑了 macOS 和 Linux 的 `canary` 二进制文件，通过 stdio 本地运行，并不需要单独的 shell 安装。Windows Claude Desktop 不受支持，因为 `canary` 没有本地 Windows 守护进程；WSL 通过下面的 shell 安装路径工作。
### Shell、Cursor、Continue、Zed 和通用 MCP 主机
```sh
curl -fsSL https://raw.githubusercontent.com/osauer/canary/main/install.sh | sh
canary setup claude-desktop
```
安装程序下载您所在操作系统和架构的发行版，验证校验和，将 `canary` 安装在 `~/.local/bin`，并在需要时将该目录添加到您的 shell rc 中。在 macOS 上，它还会清除 Gatekeeper 隔离。
`canary setup claude-desktop` 将遗留的 MCP 服务器条目写入 Claude Desktop。除非您特别想要一个共享的 shell 管理二进制文件，否则请优先使用上面的 MCPB 路径。
对于 v1.0.0+ 版本，安装程序、`canary update` 和 MCPB 版本资产都由签名的 `SHA256SUMS` 文件覆盖。MCP 注册表元数据还携带 MCPB 文件的 SHA-256。
## 您获得的内容
- **账户和仓位。** 净清算、购买力、现金、保证金、日盈亏、仓位、期权希腊字母、按底层资产分组和投资组合层面的 delta/theta/gamma/vega 汇总。多币种账户包括外汇风险敞口。
- **报价和历史。** 快照报价、合并的股票/ETF 流媒体、日 OHLCV 条形图、前一收盘价、当日涨跌幅和数据新鲜度（`live`、`frozen`、`delayed`、`delayed-frozen`）。
- **官方市场日历。** 美国现金股票、美国上市期权常规交易时段和德国 Xetra 现金股票，包含假期、提前收市、下一次开市/收市时间和报价 `session_context`，当日历状态解释陈旧或缺失的数据时。
- **本地观察列表。** 离线添加/删除/清除符号，以 JSON 列表，显示带有价格、货币、涨跌幅、范围、成交量、时间戳和持股上下文的丰富报价监视器，或使用 `canary watch --watch` 轮询保存的列表。
- **期权。** 到期列表，带有 ATM IV 和隐含变动，带有行权报价、delta 和开仓兴趣的执行网格。支持期权快照；不支持期权流媒体。
- **扫描器。** 带有移动、亏损、异常交易量、缺口、高 IV 排名和期权交易量的内置市场扫描。
- **仓位规模。** 针对实时 NLV 的固定比例规模，带有可选的目标、R 倍数和盈亏平衡胜率。纯数学；绝不订购票。
- **市场广度。** 从成分日条形图中获取 S&P 500 参与度：高于 50-DMA 的百分比，高于 200-DMA 的百分比，以及新的 52 周高/低。新的缓存是即时的；首次冷启动可能需要大约一小时，因为 IBKR 有节奏。
- **交易商 gamma。** 生产就绪的 SPX/SPXW 规范零 gamma 和集中度视图，带有 SPY 作为佐证上下文，当其期权曲面可用时。新的、可排名的 SPX 结果是稳定的头部信号；仅 SPY 是一个标记的代理。按符号级别对待，签署的级别作为状态提示，而不是精确的交易级别。
- **风险状态。** 一个调用返回八行仪表盘：VIX 期限结构、VVIX、HYG/SPY 背离、HY/IG OAS、融资利差、USD/JPY 每周变动、SPX 规范交易商 gamma 和 S&P 500 广度。重行报告 `computing` 而不是假装陈旧数据是新鲜的。
- **投资组合压力测试。** `canary stress` 和 MCP `canary_stress` 产生一个无状态的 `市场状态 × 投资组合形状` 监视器，带有 `action`、`market_confirmation`、`portfolio_fit`、`input_health`、`planner readiness`、`stable fingerprints` 和支持的 `signals[]`。它还发出有界的 `portfolio.held_stress[]` 行，用于重要的底层资产，当现有仓位数据显示持仓名称的日盈亏冲击、临近到期期权 delta 集中度或持仓名称流动性退化时。仅账户风险保留证据，而不是 DEFEND 触发器；DEFEND 需要确认的市场压力、脆弱的投资组合拟合度和干净的输入。使用 `canary stress --details` 获取完整的证据行。
- **市场事件标志。** `canary market-events` 和 MCP `canary_market_events` 用借贷库存、极端借贷费、Nasdaq Reg SHO 阈值列表、LULD 暂停和监管/新闻停牌上下文注释持仓或请求的股票/ETF 符号。标志是上下文和提案门控：活跃的停牌/LULD 可以阻止保护提案，借贷压力可以加强做空买入-卖出上下文，而未知来源仍然未知而不是错误。借贷费输出还披露全球和确切持仓-短覆盖；狭窄的 TWS `FEE_RATE` 回落仍然是不可验证的扩展，并且不能创建或清除 50% 标志。
- **保护提案和订单视图。** 守护进程维护带有每行阻止器的跟踪止损、theta 卫生和风险降低提案，`canary proposals` 和 MCP `canary_proposals` 读取它们。订单状态是一个本地日志读取（`canary orders open`、`canary orders history`、`canary order status`），它在每次重新连接后和每 30 分钟与经纪人的开仓列表进行调和，关闭经纪人不再报告的行作为 `closed_reconciled`。如果保护止损不再与其仓位匹配，则会标记为关键并显示确切的减少到仓位数量。这些是读取；对任何操作保持在单独的门控订单路径后面。
- **平台设置。** `canary settings show` 和 MCP `canary_settings` 报告运行时偏好、交易/构建能力、账户模式和紧凑的观察市场数据质量，带有 `access`、`source` 和只读原因。`features.purge_restore.enabled` 控制工作流/读取表面，而 `purge status` 保持可读；它从不授权经纪人提交，目前不可用，必须在 TWS 中手动处理。
每个数据命令都支持 `--json`。`canary restart --json` 也适用于脚本：它报告是否已经运行的守护进程、旧/新 PID、是否使用 `--force`、启动后的 `status.health` 快照以及任何刷新应用程序进程。
有关模式和边缘情况，请参阅 [agent skill schema notes](skills/canary/schemas.md)、[MCP 工具参考](docs/docs/reference/mcp-tools.md)、[MCP 资源参考](docs/docs/reference/mcp-resources.md)、[配置参考](docs/docs/reference/config.md) 和 [概念文档](docs/docs/understand/concepts.md)。
有关现成提示，请参阅 [examples/canary_portfolio_analysis_prompt.md](examples/canary_portfolio_analysis_prompt.md) 进行投资组合审查，以及 [examples/canary_portfolio_stress_prompt.md](examples/canary_portfolio_stress_prompt.md) 进行计划压力检查。
## 选择您的路径
### Claude Desktop、Cursor、Continue、Zed
`canary mcp` 启动一个本地 stdio MCP 服务器。MCP 主机可以调用与 CLI 公开的相同账户、观察列表、报价、日历、仓位、扫描器、规模、状态、压力和仅预览订单草图工具作为 JSON。订单预览表面可以创建本地不提交的预览令牌，但不能放置、修改、取消或传输经纪人订单。MCP 访问观察列表可以通过返回保存的符号或丰富的报价行；本地生命周期动词如 `setup`、`update`、`restart`、`mcp` 和 `daemon` 保留在 MCP 工具集之外。
服务器还为股票和 ETF 公开报价作为 MCP 资源：
- `canary://quote/{symbol}`
`resources/read` 为该 URI 返回一个快照；`resources/subscribe` 通过 `notifications/resources/updated` 交付合并的 tick，直到您 `resources/unsubscribe` 或关闭 stdio。资源形状在 [docs/docs/reference/mcp-resources.md](docs/docs/reference/mcp-resources.md) 中记录。
对于 Claude Desktop，推荐的安装路径是从最新版本获取 `.mcpb` 资产。对于其他客户端，请将此内容粘贴到客户端的 MCP 配置中（路径各不相同）：
```json
{
"mcpServers": {
"canary": {
"command": "/ABSOLUTE/PATH/TO/canary",
"args": ["mcp"]
}
}
}
```
`command` 必须是绝对路径。`~` 不会被 `exec` 扩展，而 `$PATH` 不会被查询。`which canary` 给出正确的值。升级二进制文件后，请完全退出并重新启动客户端 - 它缓存了生成的服务器进程。MCPB 安装包含其自己的嵌入式二进制文件；重新安装新的 `.mcpb` 版本以更新该路径。
`claude.ai`（web）仅接受远程 MCP 服务器，无法访问本地 IB Gateway。使用 Desktop。
日志（macOS，Claude Desktop）：`~/Library/Logs/Claude/mcp-server-canary.log`。
### Claude Code
在独立的 Claude Code 会话中：
/plugin marketplace add osauer/canary
/plugin install canary@canary
或 - 对于 **Claude for Mac** 的嵌入式 Claude Code 窗格，它不公开 `/plugin` 斜杠命令 - 从常规终端：
```sh
claude plugin marketplace add osauer/canary
claude plugin install canary@canary
```
插件带有技能、Claude Code MCP 服务器配置的 `canary mcp`、`PreToolUse` 钩子，允许读取/预览订单命令，阻止 shell 命令链接到经纪人相邻的写入，并且除非守护进程报告纸或实时交易状态（如果 PATH 中缺少 `jq`，则关闭经纪人相邻的 `canary` 命令），否则拒绝经纪人写入动词，以及二进制文件安装的提示。技能的 `allowed-tools` 预允许读取和仅预览模式，一旦技能激活。对于全局允许列表，在技能激活之前触发，先合并 `settings/canary.settings.json` 到 `~/.claude/settings.json` - 它仅限于权限：读取/预览模式被允许，破坏性守护进程维护具有明确的拒绝规则，而经纪人写入由钩子和守护门控决定。
**插件不包含二进制文件。** 它带有技能、钩子、MCP 启动器配置和清单 - 您仍然需要来自 [安装](#安装) 的 `canary` 二进制文件。MCP 启动器查看 `CANARY_BIN`、插件的本地开发 `bin/canary`、`PATH`、`~/.local/bin/canary`、Homebrew 和 `/usr/local/bin/canary`。二进制文件和插件有独立的发布节奏和独立的更新路径：
```sh
# 二进制文件发布（新的 MCP 工具描述被烘焙到二进制文件中）：
curl -fsSL https://raw.githubusercontent.com/osauer/canary/main/install.sh | sh
# 插件发布（新的技能命令、设置、钩子）：
claude plugin update canary@canary
```
在更新二进制文件后，请重新启动主机（Claude for Mac、独立的 Claude Code 会话、Cursor、...），以便它重新生成 MCP 服务器子进程并加载新的描述，并在下一个会话启动时重新加载技能。
### Shell
```sh
$ canary account --json | jq '.net_liquidation, .base_currency'
$ canary watch IBM --add
$ canary watch --list --json
$ canary watch --json | jq '.rows[] | {sym: .symbol, price: .price, chg: .change_pct, as_of: .price_as_of}'
$ canary quote AAPL,MSFT --json | jq '.[] | {sym: .symbol, price: .price, chg: .change_pct}'
$ canary quote MBG --market de --json | jq '{sym: .symbol, ccy: .contract.currency, last: .last}'
$ canary calendar --market us-options --date 2026-11-27 --json | jq '.session'
$ canary positions --by underlying --json | jq '.portfolio.effective_delta'
$ canary stress --json | jq '{action, market_confirmation, portfolio_fit, held_stress: .portfolio.held_stress}'
$ canary market-events --symbol GME --json | jq '{flags, source_health, fingerprint}'
$ canary settings show --json | jq '.features.purge_restore.enabled'
$ canary chain NVDA --json | jq '.expiries[] | select(.iv > 0.6)'
$ canary size --symbol AAPL --entry 207.50 --stop 202.50 --risk-pct 1'
```
`canary --help` 列出子命令；`canary <cmd> --help` 列出标志。`canary status` 如果任何内容看起来不正确，请先执行。
### 移动应用
`canary app` 提供了移动应用的 PWA，用于 iPhone 大小的检查：当您不在办公桌旁时，可以进行守护进程状态、账户和仓位、市场上下文、状态警报和设置。应用有监控、警报和设置选项卡；设置可以切换清除/恢复工作流偏好，但经纪人提交仍然不可用，需要手动 TWS 操作。在 Mac 上运行 TWS 或 IB Gateway，然后运行 `canary app pair` 并扫描二维码。
对于访问 LAN 之外的访问权限，无需路由器设置，请运行 `canary app --remote` 以使用 `remote.osauer.dev` 的 Cloudflare Worker 继电器，然后像往常一样运行 `canary app pair`。
参见 [web/app/README.md](web/app/README.md) 获取简短的操作员说明，以及 [internal-docs/design/mobile-app-mvp.md](internal-docs/design/mobile-app-mvp.md) 获取 MVP 设计。
### Go 和其他代理 SDK
`pkg/ibkr` 直接使用 TWS API 协议：
```go
import "github.com/osauer/canary/v2/pkg/ibkr"
cfg := ibkr.DefaultConfig() // 127.0.0.1:4001
cfg.Port = 4002 // 模拟
c := ibkr.NewConnector(&ibkr.ConnectorConfig{
ServiceName: "myapp",
PreferredClientID: 15,
BaseConfig: cfg,
})
if err := c.Start(ctx); err != nil { return err }
snap, err := c.RequestAccountSummary(ctx, 5*time.Second)
if err != nil { return err }
if snap.NetLiquidation != nil {
fmt.Printf("NLV: %.2f %s\n", *snap.NetLiquidation, snap.Currency)
}
```
从 Python、TypeScript 或 Rust 调用 shell：subprocess in，JSON out。将每个 `canary <cmd> --json` 调用包装成一个函数，并将其注册到您的模型的工具调用 API 中。
## 工作原理
`canary` 运行本地命令以对抗一个后台守护进程。
当您运行 CLI 命令或 MCP 工具时，它会通过 Unix 套接字与守护进程连接。守护进程保持 IB Gateway 或 TWS 连接打开，缓存合约详细信息，管理报价订阅，并返回 JSON 响应。它在首次使用时启动，并在 15 分钟不活动后退出，除非您在前台运行它。
```text
CLI 或 MCP 主机 -> 本地 canary 守护进程 -> IB Gateway 或 TWS -> 您的账户数据
```
使用 `canary restart` 在升级、更改守护进程加载的配置或要清除陈旧网关连接状态时。 它发送 SIGTERM，等待清理，启动一个新的守护进程，报告新进程，然后刷新任何已运行的 `canary app` 主机，同时保留应用程序标志，例如 `--remote`。 如果没有运行守护进程，它会启动一个并说明；如果没有运行应用程序主机，它会让应用程序停止。 `canary restart --force` 升级为 SIGKILL，仅在正常超时后。 这重新启动由 CLI 和 MCP 工具调用共享的守护进程；它不会重新启动 `canary mcp` stdio 进程本身，该进程由 MCP 主机拥有。 当您需要它从新的二进制或包中重新生成 MCP 时，请完全重新启动主机。
这意味着您的 shell、Claude Desktop、Claude Code、Cursor 和其他 MCP 客户端可以共享一个 IBKR 连接和一个客户端 ID。 工具调用保持快速，因为网关会话已经打开。
`pkg/ibkr` 是 TWS 协议的干净的 Go 实现。 默认构建中禁用无限制订单方法；单独的交易构建和狭窄的全构建纸订单包装器具有不同的门控，描述在 [docs/docs/internals/protocol.md](docs/docs/internals/protocol.md) 中。 公共包文档位于 [pkg/ibkr/doc.go](pkg/ibkr/doc.go)。
## 配置
对于正常的只读使用，不需要配置文件。 守护进程 TCP 探测 `4001`（网关实时），`4002`（网关纸质），`7496`（TWS 实时），`7497`（TWS 纸质），选择第一个响应者，如果第一个响应者接受 TCP 但从未完成握手，则回退到备用。 账户通过 `managedAccounts` 自动检测。 默认客户端 ID 为 `15`。
**TOML 配置**（`config.toml`）表示“主动本地覆盖”。 仅当您要固定某些内容时才创建它：存在的内容是绑定的，省略的内容保持自动检测，未知的键会在启动时失败，并带有命名它们的错误消息。 安全固定的预重命名命名空间仍为 `$XDG_CONFIG_HOME/ibkr/config.toml`，回退到 `~/.config/ibkr/config.toml`，因此升级无法创建第二个配置权限。 例如，此只读配置固定 TWS 实时并使其他所有内容自动：
```toml
[gateway]
port = 7496
```
每个部分和键 - `[gateway]`、 `[daemon]`、 `[trading]`、 `[rulebook]`、 `[auto_trade]`、 `[opportunities]`、 `[spx]`、 `[scans.<name>]` - 都在生成的 [configuration reference](docs/docs/reference/config.md) 中列出，并具有类型、默认值和语义， 以及公共 `CANARY_*` 变量和代理线 `IBKR_*` 诊断。 `canary status` 显示守护进程最终使用的内容以及每个值来自哪里（“固定”或“发现”）。
**运行时平台偏好** 由守护进程拥有，位于安全固定的 `$XDG_STATE_HOME/ibkr/daemon.db` 中，并在不重启的情况下更改。 功能开关和规则手册收益覆盖可通过 `canary settings set`、SPA 设置选项卡或 `PATCH /api/settings` 获得； `trading.freeze` 制动器和实验性交易限制覆盖需要来自交互式人类终端的 `canary settings set`。 可写键在 [configuration reference](docs/docs/reference/config.md) 中列出；所有权和语义位于 [platform-settings design](internal-docs/design/platform-settings.md) 中。
**交易政策** 将交易台的风险决策转化为可重复的检查。 个人风险宪法位于 `~/.config/ibkr/policies/risk-policy.toml`；此安全固定的路径防止重命名隐藏已批准的政策。 它没有嵌入式默认值：缺少的材料决策仍为“未批准”。 保护提案（`protection-policy.toml`）和期权行权机会（`opportunity-policy.toml`）确实具有保守的嵌入式默认值，可使用 `canary policy default <protection|opportunity>` 打印。 [trading-policy reference](docs/docs/understand/policy.md) 解释了谁决定风险边界，如何评估它们，什么是当今的建议，哪些操作仍需要人类。 每个可编辑的引擎键仍在生成的 [configuration reference](docs/docs/reference/config.md) 中列出。
**交易配置是可选且实验性的。** 稳定的 `canary` 版本是只读的。 交易构建在构建或单独发布时是实验性的，并按原样提供，供明确的操作员测试。 保持交易配置处于非活动状态作为 `~/.config/ibkr/config.toml.trading`；它在具有该后缀时无效。 要激活它，人类或明确指示的本地代理删除 `.trading` 后缀，以便文件变为 `~/.config/ibkr/config.toml`，验证固定的帐户和端点，然后运行 `canary restart`。 示例模板位于 [examples/config.toml.trading](examples/config.toml.trading)。
参考：
- [Configuration reference](docs/docs/reference/config.md) 获取 TOML 部分和 `IBKR_*` 环境变量。
- [Trading policy](docs/docs/understand/policy.md) 获取谁决定风险边界、Canary 如何评估它们、什么是当今的建议，哪些操作仍需要人类。
- [Trading Rulebook](internal-docs/design/trading-rulebook.md) 获取编译的建议纪律模型、其证据合约、所有权、新鲜度和限制。
- [Storage](docs/docs/internals/storage.md) 获取守护进程如何使用 SQLite 保存状态和证据，包括数据关系、查询边界、耐久性、恢复和当前限制。
- [Sensors](docs/docs/understand/sensors.md) 获取 Gamma、Regime、Stress、Rulebook、市场事件授权、新鲜度、最近行为和关闭检查。
- [Experimental trading config](docs/docs/operate/orders.md) 获取非活动的 `config.toml.trading` 模式和发布渠道期望。
- [Concepts](docs/docs/understand/concepts.md) 获取广度、伽马和制度解释。
- [Working with agents](docs/docs/operate/agents.md) 获取 Claude 和 MCP 工作流程。
- [Packaging and distribution](docs/docs/internals/packaging.md) 获取包装说明。
- [Privacy](PRIVACY.md) 获取数据本地性和本地文件。
### 添加扫描仪
根据调用者的不同，有两种路径：
**人类 - 将预设添加到 `config.toml`。** 在您想要一个稳定的简写名称时使用此方法：
```toml
[scans.tech-gainers]
type = "TOP_PERC_GAIN"
exchange = "STK.NASDAQ"
limit = 25
```
然后 `canary scan tech-gainers`。 **注意：** 编写 **任何** `[scans.*]` 块都会使七个内置默认值消失 - `[scans]` 表是替换而不是合并。 如果您想保留它们，请从 [internal/config/config.go](internal/config/config.go) 将默认值复制到您的文件中。 运行 `canary restart` 以使新预设可见。
**代理 - 使用临时表单，不需要写入配置：**
```
canary scan --type TOP_PERC_GAIN --exchange STK.NASDAQ --limit 25 --json
canary scan --type TOP_PERC_GAIN --exchange STK.EU.IBIS --instrument STOCK.EU --limit 25 --json
```
临时行限制为 50（相对于预设的用户设置限制），以防止代理意外拉取数千行。
**查找正确的 `scanCode` 和 `locationCode`。** TWS 市场扫描仪 UI 将这些字符串隐藏在人类标签后面。 使用以下命令转储网关的实际目录：
```
canary scan params --instrument STK [--json]
```
目录因网关版本和市场数据订阅而异 - `scanCode` 如 `HIGH_OPT_IMP_VOLAT_OVER_HIST` 需要美国期权数据，欧洲股票位置通常需要 `--instrument STOCK.EU` 而不是美国默认 `STK`。 `--instrument STK` 缩小到美国股票扫描；省略所有扫描。 添加 `--raw` 以获取完整的 XML（〜200 KB-2 MB），如果您需要较不常见的字段。 不需要记住这些值 - 目录是事实来源。
## 安全
`canary` 是稳定的无经纪人写入二进制线。 它公开了只读工具加上预览-仅限订单草稿；预览令牌是本地工件，不是经纪人订单。 实验性交易构建是单独的，按原样提供，不支持显式操作员测试。 Go 库本身不是一个完整的无写入沙箱：其默认构建禁用无限制订单和行权方法，但保留了狭窄的纸质订单包装器，供守护进程使用。 稳定二进制的无写入姿势在这些层中强制执行：
1. 默认 `pkg/ibkr` 构建在任何线路写入之前从无限制位置/取消和期权行权方法返回 `ErrTradingDisabled`。 原始无限制方法需要 `-tags trading`；所有构建的纸质包装器验证具体的纸质帐户和连接，但不授予应用程序权限。
2. 守护进程的写入处理程序调度在 RPC 处返回 `ErrTradingDisabled` 以进行位置/取消（[internal/daemon/trading_disabled.go](internal/daemon/trading_disabled.go)）；预览可以铸造令牌，但除非经纪人 WhatIf 被接受，否则报告 `submit_eligible=false`。
3. 捆绑的 [settings/canary.settings.json](settings/canary.settings.json) 允许列表仅读取/预览 `canary` 模式，并明确拒绝破坏性守护进程维护。 经纪人写入在那里不被硬拒绝；项目钩子和守护进程门控决定它们。
4. 插件的 `PreToolUse` 钩子阻止围绕经纪人相邻写入的 shell 链接，并拒绝经纪人写入模式，除非守护进程报告纸质或实时写入就绪的交易状态，如果 PATH 中缺少 `jq`，则 `canary` 命令失败关闭。
5. `internal/mcp` 中的单元测试仅允许预览/读取模型订单工具，并拒绝非允许的订单/交易/取消/提交/放置工具名称。
稳定版本保持经纪人写入 RPC 处理程序不可用。 预览-仅限 CLI、JSON 和 MCP 添加可能会作为记录的次要添加而出现。
## 其他安装路径
- **`go install`**：`go install github.com/osauer/canary/v2/cmd/canary@latest`。 需要 Go 1.26+。
- **Claude Desktop MCPB**：从最新的 [release](https://github.com/osauer/canary/releases/latest/download/canary.mcpb) 下载 `canary.mcpb`，并使用 Claude Desktop 打开它。 版本还发布了 `canary-vX.Y.Z.mcpb` 以进行注册完整性和可复制的手动验证。
- **不同的安装目录**：`CANARY_INSTALL_DIR=/usr/local/bin sh install.sh`。 安装程序不会触摸您的 shell rc 当您覆盖时；请自行管理 PATH。
- **先检查安装程序**：`curl -fsSL https://raw.githubusercontent.com/osauer/canary/main/install.sh -o install.sh && less install.sh && sh install.sh`。
- **手动下载**：从最新的 [release](https://github.com/osauer/canary/releases/latest) 中选择一个 tarball。 每个 tarball 都包含 `canary` 加上 `LICENSE` 和 `README.md`。 使用发布签名密钥验证 `SHA256SUMS.asc` 对 `SHA256SUMS`，然后使用 `SHA256SUMS` 验证 tarball；参见 [SECURITY.md](SECURITY.md#release-integrity-v100)。
- **本地构建**：`git clone … && make install`。
- **自我更新**：`canary update` 获取下一个稳定版本，验证 `SHA256SUMS` 上的 PGP 签名，SHA 验证 tarball，然后原子替换 `~/.local/bin/canary`。 之前的字节仅在事务暂存中存在，并在发布后删除；前向守护进程状态迁移使得可执行回滚不安全。 有关无头标志矩阵、守护进程重启语义、 `canary restart` 以及运行时 S\&P-500 成分刷新工作原理的信息，请参见 [docs/docs/start/updating.md](docs/docs/start/updating.md)。
Windows 不受支持 - 守护进程使用 Unix-only 原语（setsid，flock，AF_UNIX 套接字）。 WSL 有效。
## 测试
```sh
make check # gofmt + go vet + staticcheck + govulncheck + plugin/parity checks
make test # check + unit tests + integration tests against a live gateway
```
`make check` 是绑定门控。 它在 stdlib 漏洞上失败，因此过时的 Go 工具链是构建失败。 lint/vuln 工具在 `go.mod` 中固定，并在 `go tool` 上运行，因此 CI 和本地检查使用相同的版本。 门控还检查 MCP 工具、流媒体资源、生成的引用和插件元数据是否与 CLI 命令保持一致。
`test/integration/` 下的集成测试连接到 `127.0.0.1:4001` 上的实时 IB Gateway，当它不可达时干净地跳过，因此 `go test ./...` 不会在没有网关的笔记本电脑上挂起。 使用 `IBKR_TEST_PORT=4002 make test` 覆盖端口。
没有模拟守护进程。 `pkg/ibkr/protocoltest/` 是一个线路级编码器/解码器规范，由单元测试使用。 行为验证在真实的 IB Gateway 上运行。
## 故障排除
**“网关在 12 秒内未响应 TWS 握手”。** 网关接受您的 TCP 连接，但从未回复 v100 握手。 几乎总是 API 套接字被禁用。 启动 TWS，接受“启用 ActiveX 和 Socket Clients”，退出 TWS，重启 Gateway。 标志通过共享 `~/Jts/<userdir>/ibg.xml` 携带。 它还会静默取消勾选，当 TWS / IB Gateway / IBKR Desktop / IBKR Desktop 启动到同一个登录名时 - 如果它一直返回，请仅运行其中一个。
**“未在 127.0.0.1 端口找到 IBKR 监听器...”。** 自动发现探测了所有四个标准端口，但一无所获。 错误消息告诉您属于哪种情况：如果 TWS / IB Gateway / IBKR Desktop 正在运行，API 套接字已关闭（未选中复选框，登录待处理或非默认套接字端口 - 在 `[gateway]` 中固定）；如果没有任何运行，请启动一个，守护进程会自动重新连接。 在非环回主机上，请显式设置 `host = “192.168.x.y”` - 自动发现仅探测环回。
**“发现的端点均未完成 TWS 握手”。** Gateway 和 TWS 都运行，两个都接受 TCP，但都不完成 API 握手。 通常是当天早些时候的陈旧 Gateway 窗口加上一个全新的登录 TWS。 状态输出命名尝试的每个端点。 退出您不需要的。
**“守护进程套接字未出现”。** 守护进程在启动期间崩溃。 检查安全固定的 `~/.local/state/ibkr/ibkr-daemon.log`。 常见原因：网关未运行，配置的 `client_id` 已在使用中，端口错误。 崩溃守护进程的孤儿套接字会自动处理。
**报价超时。** 严格的实时授权，市场关闭。 守护进程默认为 `SetMarketDataType(2)`（冻结），返回已知价格；仅实时快照在交易时间以外为空。 放松网关的市场数据权限。
**“使用关闭的网络连接”期间的握手。** IB Gateway 速率限制快速握手重试。 等待 ~30 秒后重启。
**CLI vs 守护进程版本偏差警告。** 运行 `canary restart`。 它停止旧守护进程并启动一个来自当前二进制的新守护进程。
**捕获诊断的线路协议。** 设置 `IBKR_WIRE_INTERCEPTOR=1` 启用进程内记录器；将其与 `IBKR_WIRE_LOG_PATH=/path/to/wire.jsonl` 结合使用，还要持久化每个帧为 JSON-lines。 `IBKR_WIRE_RING_SIZE=N` 设置内存环（默认为 256）。 对于原始字节，`IBKR_PACKET_LOG_TEMPLATE=/path/to/packets.bin` 启用较低级别的包记录器。 所有四个默认关闭。 捕获的帧携带账户敏感数据 - 参见 [SECURITY.md §Diagnostic data sensitivity](SECURITY.md#diagnostic-data-sensitivity) 在共享日志之前。
## 免责声明 & 商标
该项目是 **独立的第三方客户端**，用于 Interactive Brokers 的 [公开记录的 TWS API](https://interactivebrokers.github.io/)。 它不是由 Interactive Brokers Group, Inc. 或其任何关联方构建、背书、赞助或支持的。
- “Interactive Brokers”，“IBKR”，“TWS”和“IB Gateway”是 Interactive Brokers Group, Inc. 或其关联方的商标或注册商标。 它们在此仅用于标识此项目连接到的经纪人和 API。
- `pkg/ibkr` 是 TWS 线路协议的干净的 Go 实现。 **Interactive Brokers 分发的代码库、库或 jar 未在此项目中包含或重新分发。**
- 本项目不会存储、缓存或重新分发 IBKR 市场数据。 所有数据实时读取自您运行的网关，针对您自己的帐户，并且通过此代码永远不会离开您的机器。
- 连接到 IBKR 需要一个 **IBKR Pro** 帐户； IBKR Lite 不包括 API 访问权限。
- 这里没有任何投资建议。 使用风险自负； MIT 许可证的 AS IS 条款完全适用。
如果您是 Interactive Brokers，并且对存储库的任何内容有疑虑，请打开一个 GitHub 问题，我们将及时回应。 ## 许可证
MIT。参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器