ibkr-mcp

MCP server for Interactive Brokers — read positions, orders, P&L, and trade via the IBKR Client Portal API.

Built for use with Claude Code, Claude Desktop, and any MCP-compatible client.

Features

• Account: Net liquidation, buying power, cash balance, excess liquidity
• Positions: Open positions with real-time P&L, market value, average cost
• Orders: View all orders (open, filled, cancelled)
• Market Data: Real-time quotes, contract search
• Order Placement: Market, limit, stop, and stop-limit orders (disabled by default)

Prerequisites

1. An Interactive Brokers account (Pro or Lite)
2. Client Portal Gateway running locally
3. Node.js 18+

Setting up the Client Portal Gateway

Download the gateway from IBKR, then:

cd clientportal-gw
bin/run.sh root/conf.yaml

Log in at https://localhost:5000 in your browser. The gateway session stays alive as long as the server keeps sending heartbeats (handled automatically by this MCP server).

Installation

git clone https://github.com/YOUR_USERNAME/ibkr-mcp.git
cd ibkr-mcp
npm install
npm run build

Configuration

Copy .env.example to .env and fill in your account ID:

cp .env.example .env

Variable	Description	Default
IBKR_GATEWAY_URL	Client Portal Gateway URL	https://localhost:5000
IBKR_ACCOUNT_ID	Your IBKR account ID	(required)
IBKR_ALLOW_ORDERS	Enable order placement	false
IBKR_PAPER	Paper trading mode	true

Usage with Claude Code

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "ibkr": {
      "command": "node",
      "args": ["/path/to/ibkr-mcp/dist/index.js"],
      "env": {
        "IBKR_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
        "IBKR_PAPER": "true",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

Available Tools

Tool	Description
account_summary	Account balances, buying power, net liquidation
auth_status	Check gateway authentication status
reauthenticate	Trigger gateway reauthentication
get_positions	All open positions with P&L
get_orders	All orders in current session
search_contract	Search for a contract by symbol
get_quote	Real-time market quote by contract ID
place_order	Place an order (requires IBKR_ALLOW_ORDERS=true)

Safety

Order placement is disabled by default. You must explicitly set IBKR_ALLOW_ORDERS=true to enable it. This is intentional — start with read-only access on a paper account before enabling trading.

The IBKR_PAPER=true default connects to the paper trading port. Switch to false only when you're ready for live trading.

License

MIT