Portfolio review with Claude and IBKR

Updated: 2026-07-18 21:05 CEST

canary mcp lets Claude review an Interactive Brokers portfolio from the same local IB Gateway or TWS session a trader already uses. The job is to give an assistant enough structured account, position, option, quote, calendar, scanner, sizing, and regime context to do the kind of review a disciplined trader would otherwise assemble by hand.

A review session can also lean on the discipline surfaces: canary_rules evaluates a 14-rule daily checklist over the live book (concentration, premium caps, theta budget, expiry runway, earnings coverage, hedge integrity) and names its offenders. Missing data degrades to unknown rather than a false pass, so a cold daemon cannot flatter the book. In the terminal, canary policy reports drawdown against a risk policy you wrote yourself, and canary recon checks the daily broker statement against your declared ledger.

The review stays separate from execution: collect account and market evidence, name the missing inputs, and decide which questions deserve a closer look.

Who this is for

Use this workflow when you already trade through IBKR and want a second screen that can read the portfolio, organize the evidence, and make the next questions explicit.

It fits traders who care about:

• exposure by underlying, not just a flat position list
• options delta, theta, gamma, vega, and expiry concentration
• stale or delayed market data before acting on a quote
• watchlist names that suddenly matter because they are now near levels or have unusual volume
• portfolio risk in the context of volatility, breadth, credit, dealer gamma, and funding conditions
• sizing a trade plan before any separate execution step

Today, the public bundled MCP tools are analysis and sizing tools. They do not place, modify, or cancel orders. That boundary keeps the review workflow clean: first collect the evidence, then decide what deserves attention, then handle execution through whatever approved trading path you trust.

What Claude can inspect

A good portfolio review needs more than balances and positions. Through canary mcp, Claude can call:

• canary_account for net liquidation, buying power, cash, margin, and daily P&L
• canary_positions for holdings, option legs, Greeks, and per-underlying grouping
• canary_quote and canary://quote/{symbol} for snapshot and streaming stock or ETF quotes
• canary_calendar for official session, holiday, and early-close context
• canary_chain for option expiries, IV, expected move, strikes, deltas, and open interest
• canary_watch and canary_scan for watchlist and market-discovery context
• canary_breadth, canary_gamma, and canary_regime for market background and broad-market lifecycle
• canary_stress for portfolio-aware lifecycle, readiness, source-health, and stress checks
• canary_size for fixed-fractional position sizing math

The assistant should not treat any single tool result as a trade signal. The value is in combining the evidence, naming uncertainty, and showing which follow-up checks would change the decision.

Use this prompt

Start with the maintained prompt in examples/canary_portfolio_analysis_prompt.md. It keeps evidence, data quality, and follow-up questions separate from orders.

Short version to paste into Claude:

Review my IBKR portfolio using the Canary MCP tools. Start with account state,
positions grouped by underlying, options Greeks, quote freshness, and the current
risk-regime lifecycle. Rank the risks I should inspect today, explain the evidence
behind each one, and separate observations from possible next actions. Do not
place or imply orders.

For a deeper review, use the full example prompt and let Claude decide which MCP calls are needed before it writes the answer.

For a scheduled stress check that preserves lifecycle stage, planner readiness, source health, fingerprints, confidence, rows, and warnings, use examples/canary_portfolio_stress_prompt.md.

What a useful answer looks like

A strong review is compact, evidence-led, and explicit about missing data. It should read like a desk note, not a stream of tool output.

Sanitized sample:

Executive snapshot
- Account state is usable for review. Buying power and margin are available; no order action was taken.
- The portfolio is concentrated in three underlyings. One options position drives most of the effective delta.
- Two quotes are delayed or outside the regular session, so marks should be treated as review inputs, not live execution prices.

Risk dashboard
- Market regime: risk-on but narrowing breadth. Treat long exposure as acceptable only if single-name concentration is intentional.
- Dealer gamma: near neutral. Do not assume intraday mean reversion from this row alone.
- Options: one expiry dominates near-term theta. Check whether that is intended before adding exposure.

Top findings
1. Underlying A has the largest effective delta after options. The stock line understates the true exposure.
2. Underlying B has stale quote context. Recheck during the next open session before sizing anything.
3. Underlying C has high implied move versus recent realized range. Review whether the option premium is still paying for the risk.

Next review steps
- Pull fresh quotes for the three largest underlyings during the regular session.
- Inspect the option chain around the dominant expiry before changing the position.
- Run sizing math only after the stop and invalidation level are stated in price terms.

It is a structured review loop: current account state, current market context, current uncertainties, and the next checks that would make a decision better.

How to install

Claude Desktop users can install the MCP Bundle:

https://github.com/osauer/canary/releases/latest/download/canary.mcpb

Claude Code users can install the plugin:

/plugin marketplace add osauer/canary
/plugin install canary@canary

Shell, Cursor, Continue, Zed, and generic MCP users can install the binary:

curl -fsSL https://raw.githubusercontent.com/osauer/canary/main/install.sh | sh
canary status

Generic MCP configuration:

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

Requirements: IB Gateway 10.37+ or TWS running locally, plus an IBKR Pro account with TWS API access.

Related pages

• IBKR MCP server for the short setup path.
• Claude Desktop Install for the MCPB path.
• Working with agents for natural-language workflows.
• MCP tools reference for exact tool schemas.