ibkr-mcp

<img src="https://img.shields.io/badge/MCP-Interactive%20Brokers-red?style=for-the-badge" alt="IBKR MCP"> ibkr-mcp

An MCP server that gives AI assistants real-time access to your Interactive Brokers account via the Client Portal Web API.

<a href="#quick-start">Quick Start</a> • <a href="#tools">Tools</a> • <a href="#ibeam-setup">IBeam Setup</a> • <a href="#configuration">Config</a>

---

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

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

---

Built with the <a href="https://modelcontextprotocol.io">Model Context Protocol</a>