Canary
Market data with source quality
The daemon evaluates entitled account and market sources and preserves their freshness, warning codes, and session context. A fallback or held value never becomes green merely because it exists.
Local Interactive Brokers risk desk
Account, market, and risk context from your local broker session
Canary connects TWS or IB Gateway to a command line, a paired app, and local MCP hosts. One daemon composes the daily brief, current portfolio and market evidence, and a broker-confirmed review of what past position changes delivered.
Canary Edge compares adequately repeated stock and ETF changes with leaving the prior position unchanged, while broker-recorded option P/L stays actual-only. Delayed, held, unavailable, and not-due inputs do not masquerade as live data.
The MCP surface is read-only: no resources, settings writes, order previews, or execution 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.
Local by default
Connects to IB Gateway or TWS on your machine. No hosted broker custody layer.
Agent-ready
Runs as a stdio MCP server for Claude Desktop, Claude Code, Cursor, Zed, and other MCP hosts.
Desk functions
Daily brief, Action Queue, 14-rule rulebook, operator-written risk policy, and daily reconciliation.
Go binary
One installable CLI with a local daemon and a clean-room Go TWS protocol library.
Why there is a bird.
The market runs six and a half hours a day. You have a day job and a boss who expects eye contact. So you write your rules down, and the bird keeps the watch: one buzz on your phone when one of them needs your attention, in time to act.
Install for Claude Desktop first.
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?"What the desk includes.
Ten pieces that matter most. The changelog carries the rest.
Works with the agent you already use
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.
One queue for decisions
Current and recovered alerts, protection proposals, and option-exercise opportunities converge into one ranked app surface with explicit boundaries.
Review and Ready
The daemon composes the last completed session, the next session, source degradation, and the few rows that need a decision.
A 14-rule trading rulebook
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.
A risk policy you write yourself
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.
Daily statement reconciliation
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.
Protection proposals
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.
One daily brief, wherever you work
Monitor includes the daemon-authored daily brief: a lead verdict followed by Review for the last completed session and Ready for the next one. canary brief prints the same briefing in the terminal, while canary_brief lets Claude and other MCP clients read it without signing anything off or changing process state. Sources the daemon could not read are named rather than skipped, so missing evidence never looks clean. An experimental relay adds phone access away from home.
Read-only by default
Standard downloads compile in no broker-write path, and MCP has no preview or execution tools. The opt-in trading binary keeps constrained CLI/app actions behind confirmation, journaling, daemon policy, and freeze gates.
Ask portfolio and market questions in plain language.
The MCP descriptions are written for agent routing, so assistants can pick the right tool without you naming commands.
- Review my portfolio and rank the risks I should look at today.
- What is in my IBKR account?
- Show my SPY exposure, including option deltas.
- What does today's brief say is ready or blocked?
- Which inputs are stale, held, degraded, or unavailable?
- Show daily technical evidence for MSFT and NVDA.
- Which protection or option-exercise candidates need review?
- Which of my discipline rules is the book breaking today?
One local authority, three integration surfaces.
For AI assistants
canary mcp exposes read-only tools for status, account, positions, option strategies, named-symbol technical analysis, broker-reporting status, the retrospective Edge review, brief, rules, proposals, opportunities, settings, readiness, and order-lifecycle reads.
For fast checks
Run canary status, canary positions, canary technical, canary brief, canary rules, canary policy show, and canary recon show. The generated CLI reference carries the exact 22-command contract.
For custom systems
github.com/osauer/canary/v2/pkg/ibkr speaks the TWS protocol directly with no Python bridge and no IBKR jars.
Experimental remote Canary app.
The paired Canary PWA opens on Monitor and can run through a beta HTTPS relay when you want phone access away from the LAN. Monitor carries the daily brief; Positions, Edge, Alerts, and Orders own the deeper reads. The app and broker session still live on your Mac; the relay is transport-only and currently maintainer-assisted for early users.
Away from the screen
You are in the water and the bird has the desk, back home on your Mac, checking the account against the rules you wrote down. While they hold, the phone by the towel stays quiet. The day one breaks, it buzzes once.
TLS-protected transport
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.
Canary remote app beta
Short setup notes, relay caveats, pairing flow, screenshots, and the current beta security model.
Documentation.
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.
Architecture
Runtime processes, typed contracts, broker and external-data flows, state ownership, and deployment boundaries.
Trading policy
Who decides risk boundaries, what Canary evaluates today, how controls change, and what never becomes submit authority.
Storage
Why the daemon uses SQLite, how the data model follows from its job, how changes become durable, and where the design must evolve.
Sensors
What Gamma, Regime, Stress, Rulebook, and market events measure, when their evidence is fresh, and how gaps fail closed.
IBKR MCP FAQ.
What is the IBKR MCP server?
canary mcp is a local Model Context Protocol server for Interactive Brokers account and market-data workflows.
Can it place orders?
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.
Does it use TWS or IB Gateway?
Yes. It connects to a local TWS or IB Gateway API session and auto-discovers the standard paper and live ports.
How does Claude Desktop connect?
Install the latest MCPB release asset, open it with Claude Desktop, and restart Claude while IB Gateway or TWS is running.
Is the market data real-time?
Broker 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.
Where does the market data come from?
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. A few regime rows are the exception and read straight from the institution that publishes them, needing no IBKR entitlement: VVIX and VIX3M closes from Cboe, credit spreads from FRED, and the funding series from the Federal Reserve and US Treasury.
Useful setup pages.
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.
Claude Desktop Install
Mac prerequisites, MCPB download, Claude Desktop install steps, and first-run checks.
IBKR MCP server
The compact overview of the local MCP server, supported hosts, and read-only boundary.
IBKR MCP TWS setup
Use Trader Workstation as the local API session behind Claude and other MCP clients.
IB Gateway MCP server
Use the lighter local Gateway process as the account and market-data source.
Read-only MCP server
The no-order-entry boundary for account and market workflows.
Portfolio review with Claude and IBKR
A practical review flow for exposures, options risk, quote freshness, and next steps.
Choosing an IBKR MCP server for Claude Code
What to evaluate in a local IBKR MCP server, and how Canary's boundary holds up.