ibkr

Agentic use

Updated: 2026-06-07 08:48 CEST

ibkr mcp makes read/status CLI operations and preview-only stock/ETF order drafts 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 Claude Code plugin is registered when you install via the marketplace. It carries the ibkr skill, safety hooks, and plugin-local MCP server config for ibkr mcp; install the ibkr binary separately. Confirm it's wired:

claude plugin details ibkr@ibkr   # Skills (1), Hooks (2), MCP servers (1)
claude mcp list                   # plugin:ibkr:ibkr connected
ibkr status                       # daemon health, gateway connection, data freshness

Direct skill installs also work in Claude Code when SKILL.md is copied under ~/.claude/skills/<name>/, but that creates only a skill command. Use the plugin path for normal IBKR installs because the MCP tools and safety hooks are plugin components.

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, ibkr_market_events ↔ ibkr market-events, ibkr_order_preview ↔ ibkr order preview, etc. — while local lifecycle verbs such as setup, update, restart, 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. The top-level envelope also carries lifecycle stage, readiness, source health, and semantic fingerprints for monitor dedupe.

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.

"Should the canary stay quiet, watch, act, rebalance, flag opportunity, or block on data quality?"

→ Claude invokes ibkr_canary.

Returns a stateless market-context portfolio monitor for scheduled stress checks. The canary combines market-regime clusters, direct SPY/VIX tape shock, current exposures, concentration, positions-only held-underlying stress, option-greeks coverage, and input-health gates into action, market_confirmation, portfolio_fit, and input_health.

The tool is deliberately high-precision: a standalone pre-market SPY drawdown or VIX spike can raise watch, while defend requires confirmed market pressure, vulnerable portfolio fit, and clean enough inputs. Account-only margin or P&L facts remain evidence; they do not become a canary DEFEND action by themselves. Missing, stale, degraded, warming, or computing inputs become explicit input-health rows instead of being treated as safe.

Held-underlying stress appears in portfolio.held_stress[] only when a material held name has a real positions-derived condition: held-name daily P&L shock, near-expiry held-option delta concentration, or held-name quote/option bid-ask degradation. For held-name market-structure context, use ibkr_market_events; the canary consumes that signal as supporting context, not as a standalone trigger. See Concepts → Canary for the fuller policy.

For a scheduler-friendly prompt that preserves action, market confirmation, portfolio fit, input health, readiness, source health, fingerprints, and warnings, use examples/ibkr_portfolio_canary_prompt.md. The current tool returns the decision surface; notifications, circuit breakers, and broker-specific automation policies are intentionally left to the host or user workflow.

"Does GME have borrow, Reg SHO, LULD, or halt context?"

→ Claude invokes ibkr_market_events with {"symbol":"GME"}.

Returns market-event flags for requested or held stock/ETF symbols: IBKR shortable-share inventory, IBKR short-stock availability fee rate, Nasdaq Reg SHO threshold-list membership, and active/recent Nasdaq LULD or regulatory/news halts. The response carries flags[], by_symbol, source_health[], warning_details[], and a semantic fingerprint.

Claude should report active flags as context and safety gates, not as standalone trade ideas. Unknown source health means unavailable evidence, not inactive. Borrow inventory and fee stress are only proposal modifiers for existing short buy-to-cover reductions; they do not justify opening or adding long exposure. Active halt/LULD flags block protection preview/submit; recent halt/LULD flags require fresh quote context.

"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.

Always read quality.rankability before treating gamma as a market-structure signal. rankable means the read is fresh and covered enough; context_only is awareness-only; blocked and unavailable are data-quality blockers.

Do not treat missing 0DTE alone as a gamma no-vote. If SPX has healthy 1-7DTE and term coverage, the result can remain rankable while still disclosing the missing 0DTE bucket in quality.coverage and warning_details. After the expiring SPXW series closes, the 0DTE bucket can be absent even when the broader SPX surface is usable.

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.

"Preview buying 10 AAPL shares."

→ Claude invokes ibkr_trading_status, then ibkr_order_preview only if the local preview gate is ready.

Returns a draft order, quote inputs, position impact, notional, warnings, and preview-token fields. token_minted means the local daemon created a preview artifact. submit_eligible means broker WhatIf accepted the exact draft and a future write path could consider the token. If broker WhatIf is unavailable or rejected, token_minted can still be true while submit_eligible and compatibility field executable are false. The preview itself does not place, modify, cancel, or transmit any broker order.

What Claude can't do here

The MCP interface intentionally has no trade-execution tool. Claude can:

If you ask Claude to "buy 100 shares of AAPL," it can preview a non-submitting draft only if you explicitly ask for preview. It cannot submit that order, and won't try to. This is a hard architectural boundary: the bundled daemon does not expose broker-write paths to MCP, 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