Portfolio review with Claude and IBKR

Updated: 2026-08-10 08:25 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 structured account, position, technical, rulebook, source-health, proposal, opportunity, and order-lifecycle context without granting execution authority.

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
named holdings whose technical or liquidity evidence deserves review
portfolio risk in the daemon-composed market and source-health context

The public MCP tools are read-only. They do not preview, place, modify, cancel, or exercise orders. That boundary keeps the review workflow clean: first collect the evidence, then decide what deserves attention, then handle execution through a separately approved path.

What Claude can inspect

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

canary_brief for Canary's assembled Review and Ready overview, including inputs it could not read
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_technical for daily evidence on explicitly named stocks or ETFs
canary_rules for ranked rulebook findings and unknown inputs
canary_proposals and canary_opportunities for read-only Action Queue candidates
canary_settings, canary_trading_status, and the three order-lifecycle tools for observed state

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 canary_brief,
then inspect account state, positions grouped by underlying, options Greeks,
data quality, and the current rulebook findings. 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 review built on the daily brief, with source health, confidence, and warnings preserved, 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
- Re-run the brief when its named source is due for refresh.
- Inspect the dominant option expiry in the paired app before changing the position.
- Review any protection or exercise candidate through its explicit confirmation boundary.

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.

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.