ibkr-mcp

Read-only MCP server for Interactive Brokers Gateway via the TWS socket API. Connects directly to your running IB Gateway on localhost — no Client Portal REST API, no bundled Java gateway, no 264 MB npm packages.

What it does

Exposes IB Gateway market data, positions, and account info as MCP tools that any MCP client (Claude Code, Claude Desktop, etc.) can call.

Read-only by design. No order placement tools. The connection uses readonly=True at the API level — IB Gateway will reject order submissions even if the code is modified.

Prerequisites

• IB Gateway or Trader Workstation (TWS) running on localhost (default port 4001)
• Python 3.11+
• An active IBKR account (paper or live)

Installation

git clone https://github.com/mark-liu/ibkr-mcp.git
cd ibkr-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Configuration

All configuration is via environment variables:

Variable	Default	Description
IB_HOST	127.0.0.1	Gateway host
IB_PORT	4001	Gateway port (4001=live, 4002=paper)
IB_CLIENT_ID	10	API client ID (must be unique per connection)
IB_MARKET_DATA_TYPE	3	1=live, 2=frozen, 3=delayed, 4=frozen-delayed
IB_RECONNECT_INTERVAL	30	Seconds between reconnect attempts
IB_CACHE_TTL	3600	Contract cache TTL in seconds

Claude Code Integration

Add to ~/.claude.json:

{
  "mcpServers": {
    "ibkr": {
      "command": "/path/to/ibkr-mcp/.venv/bin/python",
      "args": ["-m", "ibkr_mcp"],
      "env": {
        "IB_PORT": "4001",
        "IB_CLIENT_ID": "10"
      }
    }
  }
}

Then in Claude Code, tools like ibkr_quote, ibkr_positions, ibkr_historical_bars become available automatically.

Available Tools

Tool	Description	Key Parameters
ibkr_quote	Current price quotes	symbols (comma/space separated, max 20)
ibkr_historical_bars	OHLCV historical bars	symbol, duration ("1 M"), bar_size ("1 day")
ibkr_positions	Portfolio positions with P&L	—
ibkr_account_summary	NLV, cash, margin, buying power	—
ibkr_option_chain	Available expirations and strikes	symbol, exchange (optional)
ibkr_contract_search	Fuzzy search for contracts	pattern
ibkr_fx_rate	Live FX rate	pair ("EURUSD", "AUD/USD")
ibkr_connection_status	Gateway health check	—

MCP Resources

URI	Description
portfolio://positions	Current positions as context
account://summary	Account summary as context

Design Decisions

• TWS socket API, not Client Portal REST. Direct connection to IB Gateway on port 4001 via ib_async. Sub-millisecond local latency, streaming-capable, full options support. No HTTP indirection through a Java gateway.
• Persistent connection with background reconnect. If IB Gateway restarts, the server automatically reconnects without manual intervention.
• Contract caching. Qualified contracts (with populated conId) are cached for 1 hour, eliminating redundant API round-trips.
• Market hours detection. Uses exchange_calendars (NYSE) to automatically switch between live (type 1) and delayed (type 3) market data.
• NaN handling. IB returns float('nan') for missing data. Every numeric field is cleaned to None before JSON serialization.
• Rate limiting. Token bucket limiters respect IB's API limits: 45 req/s for market data, 1 req/s for historical data.
• Graceful degradation. Response cache stores last-known-good data, so tools return stale results (flagged) instead of errors during brief disconnects.

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

Tests run without a live IB Gateway — all IB interactions are mocked.

Project Structure

src/ibkr_mcp/
    __init__.py
    __main__.py       # Entry point (nest_asyncio + mcp.run)
    server.py         # FastMCP server, lifespan, tool registration, resources
    client.py         # IBKRClient: connection, caching, all data methods
    config.py         # Environment variable configuration
    cache.py          # Contract cache + response cache
    models.py         # Pydantic input validation
    utils.py          # NaN handling, rate limiter, retry, formatting
    tools/
        market.py     # ibkr_quote, ibkr_historical_bars, ibkr_fx_rate
        account.py    # ibkr_positions, ibkr_account_summary
        options.py    # ibkr_option_chain
        search.py     # ibkr_contract_search
        status.py     # ibkr_connection_status

Acknowledgments

This project was built after evaluating six existing IBKR MCP servers. While none were suitable as-is (wrong API, security issues, proprietary licenses, abandoned), each contributed patterns and lessons:

• xiao81/IBKR-MCP-Server (Apache-2.0) — FastMCP lifespan pattern with typed context, MCP resources for portfolio/account data
• ArjunDivecha/ibkr-mcp-server (MIT) — Rate limiting and retry decorator patterns, symbol validation approach, exception hierarchy design
• omdv/ibkr-mcp-server — Market hours detection via exchange_calendars, contract caching concept, market data type switching
• jeffbai996/ibkr-terminal — Background reconnect loop concept, cached degradation pattern, NaN handling throughout, subscription cleanup patterns
• code-rabi/interactive-brokers-mcp (MIT) — Tool definition and registration patterns, read-only mode enforcement approach
• rcontesti/IB_MCP (MIT) — Endpoint categorization and tool description patterns

No code was copied from any of these projects. All implementations are original.

License

MIT