How do I use ibkr-mcp-server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ibkr-mcp-server show my current positions" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

ibkr-mcp-server

MCP server that exposes Interactive Brokers via the TWS API as 14 tools: account reads, market data, contract resolution, and order placement.

Paper-by-default. Live trading requires explicit opt-in via IBKR_TRADING_MODE=live.

Prerequisites

TWS or IB Gateway running locally. Download from IBKR.
API enabled in TWS/Gateway: Configure → API → Settings
- Check "Enable ActiveX and Socket Clients"
- Uncheck "Read-Only API"
- Socket port: 7497 (paper) or 7496 (live) — defaults match this server
- Add 127.0.0.1 to "Trusted IPs"
uv installed: curl -LsSf https://astral.sh/uv/install.sh | sh

Install

git clone <this repo>
cd ibkr-mcp-server
uv sync

Configure

Copy .env.example and adjust as needed (or export the vars in your shell / MCP client config).

Register with Claude Code

Add to ~/.claude.json (or a per-project .mcp.json):

{
  "mcpServers": {
    "ibkr": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/ibkr-mcp-server",
        "run", "ibkr-mcp-server"
      ],
      "env": {
        "IBKR_TRADING_MODE": "paper",
        "IBKR_CLIENT_ID": "17"
      }
    }
  }
}

Tools

Tool	Purpose
`status`	Connection + mode + gateway info
`get_account_summary`	Cash, net liq, buying power, margin
`get_positions`	Open positions with market price enrichment
`get_pnl`	Account-level or per-position P&L
`get_executions`	Today's fills (or since ISO timestamp)
`search_symbol`	IBKR symbol search
`qualify_contract`	Resolve symbol → canonical contract with conid
`get_quote`	Snapshot bid/ask/last/volume
`get_historical_bars`	OHLCV bars
`place_order`	Place MKT/LMT/STP/STP_LMT order
`place_bracket_order`	Entry + take-profit + stop-loss
`modify_order`	Modify an existing open order
`cancel_order`	Cancel an open order
`list_open_orders`	List currently open orders

Safety

Mode gate: server reads managedAccounts on connect and verifies prefixes (DU* = paper, U* = live). On mismatch, all order tools are blocked.
Audit log: every order placement / modification / cancellation is appended as a JSON line to $IBKR_AUDIT_LOG (default ~/.ibkr-mcp-server/audit.log).
Read-only mode: set IBKR_READONLY=1 to disable all order tools.

Testing

uv run pytest                          # unit tests (default)
IBKR_INTEGRATION_TESTS=1 uv run pytest -m integration   # against a running paper gateway
uv run python scripts/smoke.py         # manual end-to-end smoke