Skip to main content
Glama
ibkr-mcp

ibkr-mcp

by yigitabi5444

What is this?

ibkr-mcp connects Claude (or any MCP-compatible AI) directly to your Interactive Brokers account through the Client Portal Web API. It's a thin, stateless wrapper — no session management, no gateway lifecycle, no tickling. Just tools that call the API.

Gateway authentication and session management is handled externally by IBeam, which runs in Docker and handles login automation + 2FA.

You: "What's my portfolio P&L today?"

Claude: Your account U1234567 is up $1,247.30 today.
        Top winners: AAPL (+$523), NVDA (+$312)
        Net liquidation: $284,521.00

Related MCP server: IBKR MCP Server

Features

  • 26 read-only tools — portfolio, market data, options, orders, scanner, watchlists, news, FX

  • Stateless — no session management, no tickling, no gateway lifecycle. IBeam handles all of that.

  • Human-readable market data — snapshot fields mapped to names like lastPrice, week52High, sector

  • Zero dependencies beyond @modelcontextprotocol/sdk and zod

  • Rate limiting — per-endpoint sliding window that waits instead of erroring

  • Snapshot warmup — auto-retries on IB's first-call empty response

Quick Start

Prerequisites

  • Node.js 18+

  • Docker (for IBeam)

  • IB account with Client Portal API access

1. Start IBeam (Gateway + Auth)

IBeam handles the Client Portal Gateway process, browser login automation, session keepalive, and 2FA. See IBeam Setup below.

docker run -d \
  --name ibeam \
  -p 5000:5000 \
  -e IBEAM_ACCOUNT=your_ib_username \
  -e IBEAM_PASSWORD=your_ib_password \
  -e IBEAM_GATEWAY_BASE_URL=https://localhost:5000 \
  voyz/ibeam

2. Install & Build MCP

git clone https://github.com/yigitabi5444/yigit_ibkr_mcp.git
cd yigit_ibkr_mcp
npm install
npm run build

3. Add to Claude Desktop

{
  "mcpServers": {
    "ibkr": {
      "command": "node",
      "args": ["/path/to/yigit_ibkr_mcp/dist/index.js"],
      "env": {
        "IBKR_GATEWAY_URL": "https://localhost:5000"
      }
    }
  }
}

IBeam Setup

IBeam is the recommended way to run the IB Client Portal Gateway. It handles:

  • Starting the gateway Java process

  • Automated browser login (headless Chrome + Selenium)

  • 2FA handling (push notification, SMS, or custom handler)

  • Session keepalive

  • Automatic re-authentication on session expiry

Basic Docker Setup

docker run -d \
  --name ibeam \
  --restart unless-stopped \
  -p 5000:5000 \
  -e IBEAM_ACCOUNT=your_username \
  -e IBEAM_PASSWORD=your_password \
  voyz/ibeam

With 2FA (Push Notification)

docker run -d \
  --name ibeam \
  --restart unless-stopped \
  -p 5000:5000 \
  -e IBEAM_ACCOUNT=your_username \
  -e IBEAM_PASSWORD=your_password \
  -e IBEAM_TWO_FA_HANDLER=PUSH \
  voyz/ibeam

Docker Compose

services:
  ibeam:
    image: voyz/ibeam
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      IBEAM_ACCOUNT: ${IB_USERNAME}
      IBEAM_PASSWORD: ${IB_PASSWORD}
      IBEAM_TWO_FA_HANDLER: PUSH

See the IBeam docs for full configuration including custom 2FA handlers, health checks, and troubleshooting.

Tools

Account & Portfolio

Tool

Description

get_accounts

List all brokerage accounts

get_account_summary

Curated: NLV, cash, buying power, margin, positions value, cash by currency

get_account_summary_full

Full 70+ field raw summary

get_account_allocation

Asset class breakdown (stocks, options, futures, cash %)

get_positions

All positions with P&L. Auto-paginates. Options include strike/right/expiry

get_position_by_conid

Single position by contract ID

get_performance

Historical NAV and time-weighted returns

get_transaction_history

Transaction log with filters

Market Data

Tool

Description

get_market_snapshot

Real-time quote with readable names (lastPrice, bid, ask, sector, week52High, etc.)

get_price_history

Historical OHLCV bars (1min to monthly, up to 5 years)

Contracts

Tool

Description

search_contracts

Search by symbol or company name

get_contract_details

Curated contract specs (trading hours, tick size, exchanges)

get_stock_contracts

Stock contracts across exchanges

get_futures_contracts

Non-expired futures by underlying

Options

Tool

Description

get_option_chain

Full option chain (composite: strikes + conids in one call)

get_option_strikes

Strike prices for a specific expiration

Orders & Trades

Tool

Description

get_live_orders

All currently working orders

get_order_status

Single order status

get_trades

Execution history (7 days)

Scanner

Tool

Description

get_scanner_params

Available scanner types and filters (cached 15min)

run_scanner

Market scanner (top gainers, most active, etc.)

Other

Tool

Description

get_watchlists / get_watchlist

Saved watchlists

get_exchange_rate

FX rates

get_news_sources

Available news providers

get_news_briefing

Market briefing from Briefing.com

get_auth_status / reauthenticate / ping_session

Session diagnostics

Configuration

Environment Variable

Default

Description

IBKR_GATEWAY_URL

https://localhost:5001

Client Portal Gateway URL (IBeam default: 5000)

IBKR_ACCOUNT_ID

(auto-detected)

Default account ID

IBKR_TIMEOUT_MS

15000

Request timeout in ms

Architecture

┌─────────────────┐     stdio      ┌────────────────┐     HTTPS      ┌─────────────┐
│  Claude Desktop  │ ◄────────────► │    ibkr-mcp    │ ────────────► │   IBeam     │
│  (MCP Client)    │                │  (stateless)   │               │  (Docker)   │
└─────────────────┘                │                │               │             │
                                    │  IBClient      │               │  CP Gateway │
                                    │  RateLimiter   │               │  Selenium   │
                                    │  26 Tools      │               │  Keepalive  │
                                    └────────────────┘               └─────────────┘

The MCP is intentionally thin — it just makes HTTP calls. IBeam owns the gateway process, authentication, session keepalive, and 2FA.

Development

npm run dev          # Run with tsx (hot reload)
npm test             # Unit tests (27 tests, mocked, no gateway needed)
npm run test:integration  # Integration tests (requires live gateway)
IBKR_GATEWAY_URL=https://localhost:5000 npm run test:integration

License

MIT


Available Tools

32 tools
get_account_allocationGet Account AllocationA
Read-only

Get asset class allocation breakdown showing distribution across stocks, options, futures, cash, bonds, etc. as percentages and values.

Inputs: accountId.

get_accountsGet AccountsA
Read-only

List all brokerage accounts with IDs and capabilities. Returns account IDs that can be used with other tools.

Inputs: no named parameters.

get_account_summaryGet Account SummaryA
Read-only

Get curated account summary: net liquidation, cash, buying power, margin, gross position value, P&L, and cash breakdown by currency. Returns the most important fields only — use get_account_summary_full for all 70+ fields.

Inputs: accountId.

get_account_summary_fullGet Account Summary (Full)A
Read-only

Get the full raw account summary with all 70+ fields including segment-level duplicates (-s suffix). Use get_account_summary for a curated version.

Inputs: accountId.

get_auth_statusGet Auth StatusA
Read-only

Check if the Client Portal Gateway is authenticated. Returns auth state, competing session flag, and connection status.

Inputs: no named parameters.

get_contract_detailsGet Contract DetailsA
Read-only

Get full contract details for a known contract ID (conid). Returns exchange, currency, trading hours, tick size, and other specs.

Inputs: conid (required).

get_exchange_rateGet Exchange RateA
Read-only

Get the current exchange rate between two currencies. Requires brokerage session (auto-acquired, auto-releases after idle).

Inputs: source (required), target (required).

get_fundamentalsGet FundamentalsA
Read-only

Get company metadata for a stock: name, sector, sectorGroup, industry, listing exchange, country, currency, asset type, options availability, CUSIP. IBKR Client Portal API does NOT expose financial statements (balance sheet, income statement, cash flow), valuation ratios (P/E, market cap, EPS), or dividend data — those fields are deprecated by IBKR. For revenue/EPS growth %, 52-week range, sector/industry from market data, use get_market_snapshot. For OHLCV history, use get_price_history.

Inputs: conid (required).

get_futures_contractsGet Futures ContractsA
Read-only

Look up non-expired futures contracts by underlying symbol.

Inputs: symbols (required).

get_live_ordersGet Live OrdersA
Read-only

List all currently live/working orders. Requires brokerage session (auto-acquired, auto-releases after idle).

Inputs: no named parameters.

get_market_snapshotGet Market SnapshotA
Read-only

Get real-time market data snapshot with human-readable field names. Returns: symbol, lastPrice, bid, ask, volume, open, high, low, close, change, changePercent, week52High, week52Low, sector, industry, avgVolume, revenueGrowthPct, epsGrowthPct, changeFrom52wkHighPct, price bands (10d/30d). Also returns peRatio, eps, dividendYieldPct, marketCap, impliedVolatility when your IB market data subscription includes them. Auto-retries on first-call warmup.

Inputs: conids (required), fields.

get_news_briefingGet News BriefingA
Read-only

Get the latest market news briefing from Briefing.com. Returns a full market commentary/analysis article.

Inputs: no named parameters.

get_news_sourcesGet News SourcesA
Read-only

List available news sources/providers from IB.

Inputs: no named parameters.

get_option_chainGet Option ChainA
Read-only

Get available option expirations and strikes for an underlying security. Returns the list of strikes for calls and puts. Fast — single API call. To get conids for specific strikes, use get_option_contracts.

Inputs: conid (required), month, exchange.

get_option_contractsGet Option ContractsA
Read-only

Get option contract details (conids) for specific strikes. Returns conids you can use with get_market_snapshot for pricing/IV. Fetches up to 10 strikes at a time to stay fast.

Inputs: conid (required), month (required), strikes (required), right, +1 more.

get_option_strikesGet Option StrikesA
Read-only

Get available strike prices for options on an underlying security for a specific expiration month.

Inputs: conid (required), month (required), exchange.

get_order_statusGet Order StatusA
Read-only

Get detailed status of a specific order. Requires brokerage session (auto-acquired, auto-releases after idle).

Inputs: orderId (required).

get_performanceGet PerformanceA
Read-only

Get historical account performance including NAV and time-weighted returns over a configurable period.

Inputs: period (required), accountIds (required).

get_pnlGet P&LA
Read-only

Get account-level profit and loss data: daily P&L (dpl), unrealized P&L (upl), net liquidity (nl), and excess liquidity (el). Requires brokerage session (auto-acquired, auto-releases after idle).

Inputs: accountId.

get_position_by_conidGet Position by Contract IDA
Read-only

Get a specific position by contract ID (conid). Returns position details including quantity, avg cost, market value, unrealized P&L, and daily P&L.

Inputs: conid (required), accountId.

get_positionsGet PositionsA
Read-only

Get all open positions for an account. Auto-paginates through all pages. Returns stocks, options, futures, etc. Each position includes: symbol, quantity, avg cost, market value, unrealized P&L, daily P&L. Option positions also include: strike, right (C/P), expiry, multiplier.

Inputs: accountId.

get_price_historyGet Price HistoryA
Read-only

Get historical OHLCV price bars for a contract. Supports various periods and bar sizes. Requires brokerage session (auto-acquired, auto-releases after idle).

Inputs: bar (required), conid (required), period (required), exchange, +1 more.

get_scanner_paramsGet Scanner ParametersA
Read-only

Get available market scanner parameters. Cached for 15 minutes. Requires brokerage session (auto-acquired, auto-releases after idle).

Inputs: no named parameters.

get_stock_contractsGet Stock ContractsA
Read-only

Look up stock contracts by symbol across all exchanges. Returns available contract variants with exchange and conid.

Inputs: symbols (required).

get_tradesGet TradesA
Read-only

Get trade execution history (current day + 6 previous days). Requires brokerage session (auto-acquired, auto-releases after idle).

Inputs: no named parameters.

get_transaction_historyGet Transaction HistoryC
Read-only

Get transaction history for accounts with optional filters.

Inputs: accountIds (required), days, type, currency.

get_watchlistGet WatchlistA
Read-only

Get contracts in a specific watchlist by ID. Requires brokerage session (auto-acquired, auto-releases after idle).

Inputs: id (required).

get_watchlistsGet WatchlistsA
Read-only

List saved watchlists. Requires brokerage session (auto-acquired, auto-releases after idle).

Inputs: no named parameters.

ping_sessionPing SessionA
Read-only

Send a tickle/keepalive to the Client Portal Gateway.

Inputs: no named parameters.

reauthenticateReauthenticateB
Read-only

Trigger re-authentication of the Client Portal Gateway session.

Inputs: no named parameters.

run_scannerRun ScannerA
Read-only

Execute a market scanner to find securities matching specific criteria. Requires brokerage session (auto-acquired, auto-releases after idle).

Inputs: type (required), location (required), instrument (required), filters.

search_contractsSearch ContractsA
Read-only

Search for securities by symbol or company name. Returns contract IDs (conids), symbol, exchange, security type, and description. Use the returned conid with other tools.

Inputs: symbol (required), isName, secType.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 32 tools

    Disambiguation4/5

    The tools are mostly distinct with clear purposes, though account summary variants and multiple option lookup tools (get_option_chain, get_option_contracts, get_option_strikes) could cause initial confusion. Descriptions are detailed enough to disambiguate.

    Naming Consistency4/5

    Most tools use a get_* verb_noun pattern, but a few like reauthenticate, ping_session, run_scanner, and search_contracts break the uniformity. All names are snake_case and readable, but the mix of get_ and action verbs is a minor inconsistency.

    Tool Count2/5

    With 32 tools, the count exceeds the 25+ threshold and feels heavy. While IBKR is a broad domain, many tools could be consolidated (e.g., account summary variants), making the surface area larger than necessary.

    Completeness2/5

    The tool set covers account, market data, scanner, watchlist, and news, but critically lacks order placement, modification, or cancellation. Without these, the server cannot perform actual trading, which is a core expectation for a brokerage MCP.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to interact with Interactive Brokers trading accounts to retrieve market data, check positions, and place trades. Includes pre-configured IB Gateway and handles OAuth authentication automatically.
      14
      161 npm
      228
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI models with secure access to Interactive Brokers trading data and functionality, enabling account management, market data retrieval, and trading operations through natural language interactions.
      18
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Connects AI assistants to Interactive Brokers for intelligent portfolio management, options analysis, risk monitoring, and automated trading strategy suggestions. Enables real-time account tracking, Greeks calculations, option chain analysis, and playbook-based risk adjustments through natural language.
      5
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables read-only access to Interactive Brokers data including contracts, market data, news, fundamentals, and portfolio/account information for LLM workflows and autonomous agents.
      19
      BSD 3-Clause