Canary
Local Interactive Brokers risk desk
Canary connects TWS or IB Gateway to a command line, Claude Desktop, Claude Code, Cursor, Zed, and other MCP hosts. It adds regime context, portfolio stress checks, a discipline rulebook, an operator-written risk policy, and daily statement reconciliation.
Quotes, chains, history, scanners, dealer gamma, and breadth come through your broker session. Canary reports whether each source is live, delayed, stale, unavailable, or not yet due; coverage follows your own IBKR subscriptions.
The bundled MCP surface is read-side only: agents can analyze, monitor, and size plans without receiving order-entry tools.
For Claude Desktop, use the MCPB install page, restart Claude, and keep IB Gateway or TWS running locally. The shell and Claude Code paths are there when you want one shared binary.
Canary is analysis software, not financial advice. Nothing it shows or says is a recommendation to buy or sell any security.
Most Mac users should start with the Claude Desktop MCPB. It bundles the local MCP server, keeps the broker session on your machine, and avoids hand-editing MCP config files.
Prerequisites: IB Gateway 10.37+ or TWS running locally, plus an IBKR Pro account with TWS API access. IBKR Lite does not include TWS API access.
The Claude Desktop path explains what the MCPB bundles, what still needs to be running locally, and the exact Mac install and restart steps.
# Claude Code plugin
/plugin marketplace add osauer/canary
/plugin install canary@canary
# restart Claude Code or run /reload-plugins after install/update
# Shell, Cursor, Continue, Zed, generic MCP hosts
curl -fsSL https://raw.githubusercontent.com/osauer/canary/main/install.sh | sh
canary setup claude-desktop
# then ask:
# "How does my IBKR account look today?"Ten pieces that matter most. The changelog carries the rest.
Snapshot quotes with freshness and spread context, a streaming quote resource, option chains with implied volatility, Greeks, and open interest, daily bars, scanners, and S&P 500 breadth. Real-time where your IBKR subscriptions cover it; delayed or unavailable states stay explicit.
One binary serves Claude Desktop, Claude Code, Cursor, Zed, and other MCP hosts. The tool descriptions do the routing, so an assistant finds the right surface on its own.
Volatility, credit, funding, FX stress, dealer gamma, and breadth in one view. The same regime stage selects which thresholds the rulebook applies.
Scheduled stress checks that combine account, exposure, regime, and data-quality gates into one action an agent can poll: stand down, watch, defend, rebalance, deploy, or confirm inputs.
A daily checklist over the live book: concentration, premium caps, theta budget, expiry runway, earnings coverage, hedge integrity. Missing data degrades to unknown, never to a false pass. Advisory throughout.
canary policy reads a file you author: protected equity floor, declared risk capital, drawdown ladder. There are no default numbers in code, and nothing it reports ever blocks an order. Terminal only.
canary recon fetches IBKR Flex statements every day and checks broker-confirmed flows against your declared ledger. Clean reports take care of themselves. Exceptions ask for you. Terminal only.
The daemon maintains trailing-stop, theta-hygiene, and risk-reduction proposals with per-row blockers, refreshed every 30 seconds. Agents read them through MCP; acting on one stays behind the separate gated order path. When a working stop no longer matches the position, the app flags it in red, sends one push, and offers a single guided fix: reduce the stop to the shares still held.
The paired Canary app gives the daily brief its own tab: Review explains the last completed session, while Ready shows the evidence and risk capacity for the next one. The daemon builds both from the same typed results the tools use. Alerts count conditions rather than rows, and closed-market data stays visibly closed instead of masquerading as fresh. An experimental relay adds access away from home.
Standard downloads compile in no order tools, and the MCP order surface is preview-only in every variant. A separately published trading build carries the gated CLI path: previews, tokens, journaling, and a freeze switch.
Terminal screenshots are generated from synthetic fixture data, so the public page shows the real CLI shape without exposing account holdings or balances.
One dashboard for volatility, credit, funding, FX carry, dealer gamma, and S&P 500 breadth.
Scheduled lifecycle, readiness, source-health, and stress checks from account, exposure, regime, and data-quality gates.
Expiry lists, ATM implied volatility, and expected moves from the local IBKR market-data session.
Underlying grouping, option legs, marks, Greek coverage, and portfolio-level exposure with sensitive values redacted here.
The MCP descriptions are written for agent routing, so assistants can pick the right tool without you naming commands.
canary mcp exposes account, positions, quote, calendar, chain, history, scanner, sizing, breadth, gamma, regime, rulebook, and stress-monitoring tools, plus a streaming quote resource. Real-time data follows your IBKR market-data subscriptions.
Run commands such as canary status, canary positions, canary stress, canary calendar, canary chain SPY, and canary regime. Since v2.1 the CLI also carries the operator risk workflow: canary policy show reads the risk policy you declared and canary recon checks daily broker statements against it. Both are advisory. Every data command supports JSON; the CLI is useful, but the Claude/MCP path is the main path.
github.com/osauer/canary/v2/pkg/ibkr speaks the TWS protocol directly with no Python bridge and no IBKR jars.
The paired Canary PWA opens on the daily desk brief and can run through a beta HTTPS relay when you want phone access away from the LAN. The app and broker session still live on your Mac; the relay is transport-only and currently maintainer-assisted for early users.
Daily brief, market regime, portfolio stress, protection, alerts, positions, and settings in the paired PWA.
The Brief tab separates the last completed session from today's readiness, with source quality and exceptions kept visible.
The phone uses HTTPS and the Mac connector uses WSS, so network intermediaries cannot read the traffic. Pairing and session authorization remain local to the app.
Short setup notes, relay caveats, pairing flow, screenshots, and the current beta security model.
The handbook runs from installing Canary through the daily desk routine, how to read each measurement, the generated command and tool references, and the system design underneath. Four pages carry most of the weight.
Runtime processes, typed contracts, broker and external-data flows, state ownership, and deployment boundaries.
Who decides risk boundaries, what Canary evaluates today, how controls change, and what never becomes submit authority.
Why the daemon uses SQLite, how the data model follows from its job, how changes become durable, and where the design must evolve.
What Gamma, Regime, Stress, Rulebook, and market events measure, when their evidence is fresh, and how gaps fail closed.
canary mcp is a local Model Context Protocol server for Interactive Brokers account and market-data workflows.
Not in the standard downloads: the installer, the Claude Desktop bundle, and the plain canary tarballs are read-only builds with no place, modify, or cancel tools compiled in. Each release also publishes a clearly marked canary-trading tarball for users who explicitly opt into order management. It ships with warnings and layered safeguards.
Yes. It connects to a local TWS or IB Gateway API session and auto-discovers the standard paper and live ports.
Install the latest MCPB release asset, open it with Claude Desktop, and restart Claude while IB Gateway or TWS is running.
Data comes through your own TWS or IB Gateway session, so entitlements match what you see in TWS: real-time where you hold IBKR market-data subscriptions, delayed otherwise. Stock and ETF quotes are also exposed as a streaming MCP resource.
Canary reads through your local TWS or IB Gateway session. Coverage and delay status follow the connected account's subscriptions and the current market session.
Start with Claude Desktop if that is where you plan to ask questions. The other pages are here for TWS, Gateway, safety, and deeper portfolio-review context.
Mac prerequisites, MCPB download, Claude Desktop install steps, and first-run checks.
The compact overview of the local MCP server, supported hosts, and read-only boundary.
Use Trader Workstation as the local API session behind Claude and other MCP clients.
Use the lighter local Gateway process as the account and market-data source.
The no-order-entry boundary for account and market workflows.
A practical review flow for exposures, options risk, quote freshness, and next steps.