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.

Related MCP server: IBKR MCP Server

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:

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

MCP Resources

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