ibkr

Agentic use

Updated: 2026-05-25 20:50 CEST

ibkr mcp makes every read-only CLI operation available to MCP clients: Claude Code, claude-desktop, or any other host that speaks the protocol. The same daemon serves the CLI and MCP. The MCP layer is a thin adapter over the existing RPCs. Official market calendars and stock/ETF quotes are also available; quote resources can be read once or subscribed to for streaming updates.

This page is for the human installing the plugin and wondering "what can I actually ask Claude with this?" For exact tool parameters and JSON envelopes, see the auto-generated MCP tools reference. For protocol mechanics, see the upstream Model Context Protocol spec.

Setup

The plugin manifest (.claude-plugin/plugin.json) is registered when you install via the Claude Code marketplace. Confirm it's wired:

ibkr status                   # daemon health, gateway connection, data freshness

The MCP tools are listed in reference/mcp-tools.md. They mirror the agent-appropriate CLI commands — ibkr_status ↔ ibkr status, ibkr_calendar ↔ ibkr calendar, ibkr_watch ↔ enriched ibkr watch by default or read-only ibkr watch --list when include_quotes is false, ibkr_gamma ↔ ibkr gamma, etc. — while local lifecycle verbs such as setup, update, mcp, and daemon stay outside the MCP tool set. Claude calls the tools as MCP operations rather than CLI subcommands.

Example conversations

These are the kinds of questions the tool handles. Each shows the user's message, the tool(s) Claude is likely to invoke from the descriptions, and what the human can expect back.

"Is the market regime favorable right now?"

→ Claude invokes ibkr_regime.

Returns the eight-row dashboard: VIX term structure, VVIX, HYG/SPY divergence, HY/IG OAS, funding spread, USD/JPY weekly move, dealer zero-gamma, and S&P breadth. Each row carries raw measurements, compact band/as-of metadata, scoped warnings when data is stale or unavailable, and a streak field when the row is rankable.

Claude composes an answer that names which indicators are in which band, calls out any in red, and flags streaks (a Day-5 stress event reads differently from a Day-1 spike). The dashboard is information, not a verdict — the user's risk tolerance determines what to do with it. See Concepts → Regime.

"Show me my SPY positions and any options on them."

→ Claude invokes ibkr_positions with {"symbol": "SPY"}.

Returns rows for SPY stock holdings and any SPY options, with per-leg Greeks (delta/gamma/theta/vega) for the options, plus a portfolio block aggregating effective_delta in share-equivalents. Claude typically renders the stock holding alongside an aggregate Greek line ("you're net long ~1,500 SPY-deltas after the options"). Daily P&L is included from IBKR's reqPnLSingle stream — null when the daemon hasn't pre-warmed that contract, never zero-substituted.

If you also want context, follow-up questions naturally chain: "and what's SPY's dealer gamma profile?" invokes ibkr_gamma; "how does that compare to where SPY closed yesterday?" invokes ibkr_history + ibkr_quote.

"What's on my watchlist?"

→ Claude invokes ibkr_watch.

Returns the enriched monitor for the local saved symbols by default: price, currency, movement, ranges, volume, freshness, and held-stock context where available. The MCP tool is read-only: Claude can use the symbols for follow-up quote, history, chain, scan, gamma, or regime context, but it cannot add, remove, or clear watchlist entries through MCP. If the user asks only for the saved symbol inventory, Claude passes {"include_quotes": false}.

"Show my watchlist with current prices and what I hold."

→ Claude invokes ibkr_watch.

Returns one row per saved symbol with headline price and currency, previous close, absolute and percent change, day range, 52-week range, volume versus average volume, price_as_of, stale/session context, and compact stock holding context where the account owns the symbol. Claude should call out stale or closed-market rows instead of treating the values as fresh live prices.

"Why does SPY look stale at 1am ET?"

→ Claude invokes ibkr_quote; if the snapshot is frozen, delayed, or missing live prices, the response may include session_context. Claude may also invoke ibkr_calendar directly to answer "when does it reopen?"

Returns the official market state for the relevant supported calendar: US cash equities, US listed options regular sessions, or German Xetra cash equities. A US quote at 1am ET will normally say the regular session is closed and show the next 09:30 ET open; a US holiday shows the holiday reason and the next known open. For example, Whit Monday 2026 is closed for US equities because it is Memorial Day, while Xetra is open.

"Are SPY dealers supporting or amplifying today's moves?"

→ Claude invokes ibkr_gamma (default scope = combined SPY+SPX).

Returns the signed zero-gamma price level, the dealer book's current sign (positive = long-gamma = stabilising; negative = short-gamma = amplifying), the regime-agreement classifier between SPY and SPX (agree:long-gamma / agree:short-gamma / agree:transition-gamma / disagree), and the magnitude view via gamma_total_abs and top_strikes.

The important diagnostic is **disagree** — one book stabilising while the other amplifies, indicating institutional/retail positioning divergence. Claude usually flags this prominently. The first call of an NY trading day kicks a multi-minute background compute; you'll see status: "computing" with an ETA — re-ask in a few minutes for the result. See Concepts → Gamma.

"Find me top S&P 500 names trading above their 50-day moving average."

→ Claude invokes ibkr_breadth to get the index-wide reading, then ibkr_scan with the top-movers preset (or an ad-hoc scan) to return specific names.

Returns the % of S&P names above their 50-DMA (the tactical signal) and per-row scanner output enriched with last / prev_close / change_pct / volume / IV. Claude typically pairs the breadth context ("market-wide reading: 54% above 50-DMA, healthy") with the specific names that match the scan. For follow-up questions like "show me daily bars for AAPL", Claude chains to ibkr_history. See Concepts → Breadth.

What Claude can't do here

The MCP interface is intentionally read-only. There is no trade-execution tool. Claude can:

If you ask Claude to "buy 100 shares of AAPL," it will tell you it can't — and won't try to. This is a hard architectural boundary: the daemon never exposes write paths to IBKR, regardless of what Claude asks.

Streaming quote resources are separate from tools. MCP clients discover the ibkr://quote/{symbol} template via resources/templates/list; resources/read gives one quote snapshot, and resources/subscribe emits coalesced tick frames through notifications/resources/updated until the client unsubscribes or closes the MCP session. This streaming resource is stock/ETF only; option streaming is not exposed.

Other things outside the scope today:

Tips for getting good answers

A few prompt patterns that work well, learned from observing real conversations:

Reference