IBKR MCP Server

An MCP server that gives AI agents 38 tools to query and trade through Interactive Brokers, built on ib_async and FastMCP.

[!WARNING] This project is designed and tested only with IBKR PAPER accounts. Six tools can place, modify or cancel real orders (place_order, place_bracket_order, place_combo_order, modify_order, cancel_order, cancel_all_open_orders). Use at your own risk. Nothing here is financial advice, and the authors accept no liability for any losses.

Features

Orders (10)

• place_order, place_bracket_order, place_combo_order — submit stock, option, bracket and combo orders
• modify_order, cancel_order, cancel_all_open_orders — change or cancel orders
• precheck_order — risk-only dry check (hours, notional, price distance, buying power, concentration)
• get_live_orders, get_order_status, get_executions — order and fill tracking

Account and data (16)

• get_positions, get_account_summary, get_portfolio_snapshot, get_pnl_per_position, get_daily_pnl_history, classify_positions_by_strategy
• get_market_data, get_historical_bars, get_52w_context, get_option_chain
• get_fundamentals, get_earnings_date, get_dividend_calendar (via yfinance)
• get_exchange_hours, resolve_symbol, screen_universe

Options analytics (9)

• get_market_data_with_greeks, bs_price, implied_volatility, greeks_from_price
• prob_itm, expected_move
• evaluate_multi_leg, pmcc_evaluator, roll_analyzer

Diagnostics (3)

• healthcheck, get_recent_errors, get_server_info

Safety by design

• Live-price gate on place_order: the order is blocked if no live price is available, or if a limit price deviates from the mid/last/close reference by more than IBKR_ORDER_PRICE_TOLERANCE_PCT (default 2.0%).
• precheck_order risk limits (configurable, evaluated when the tool is called):
  • IBKR_MAX_ORDER_NOTIONAL — max order notional, default 5000.0 (blocker)
  • IBKR_MAX_PRICE_DISTANCE_PCT — max limit-price distance from reference, default 0.10 (blocker)
  • IBKR_MAX_CONCENTRATION_PCT — max post-trade position share of net liquidation, default 0.20 (warning)
  • It also blocks when the exchange is closed or the order exceeds buying power.
• Paper port by default: the server connects to 127.0.0.1:4002.

[!NOTE] The IBKR_MAX_* limits are enforced by precheck_order, not inside the order-placing tools. The agent (or your prompt/policy) must call precheck_order before placing orders.

Quick start

Requirements: Python 3.11+, and IB Gateway or TWS running in paper mode with the API enabled (default Gateway paper port 4002).

git clone https://github.com/ettore-pedemonti/ibkr-mcp-server.git
cd ibkr-mcp-server
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python server.py   # speaks MCP over stdio

Example MCP client configuration (e.g. Claude Desktop):

{
  "mcpServers": {
    "ibkr": {
      "command": "/path/to/ibkr-mcp-server/.venv/bin/python",
      "args": ["/path/to/ibkr-mcp-server/server.py"],
      "env": {
        "IB_HOST": "127.0.0.1",
        "IB_PORT": "4002",
        "IB_CLIENT_ID": "10"
      }
    }
  }
}

Configuration

All settings are environment variables.

Testing

test_all_tools.py is a read-only regression script: it calls the read-only tools and skips the order-mutating ones. It requires a running IB Gateway/TWS in paper mode.

TEST_IB_CLIENT_ID=99 python test_all_tools.py

TEST_IB_CLIENT_ID (default 99) sets the client ID used by the script, so it does not clash with a running server.

Roadmap

• Enforce the IBKR_MAX_* risk limits inside the order-placing tools, not only in precheck_order
• Unit tests with a mocked ib_async
• GitHub Actions CI
• ruff linting and type hints

License

MIT