ibkr-mcp

A read-only-by-default MCP server for Interactive Brokers — account, positions, PnL, market data, and full trade history from a local TWS / IB Gateway session.

What it is

ibkr-mcp exposes your Interactive Brokers account to any Model Context Protocol client (Claude Code, Claude Desktop, and others) through a locally running Trader Workstation or IB Gateway, using the ib_async library.

No credentials pass through this server. You log in to TWS or IB Gateway as usual, and ibkr-mcp attaches to its API socket on 127.0.0.1. By default it is read-only: no order tools exist, and the only outbound network call it can make is the optional Flex history fetch, pinned to interactivebrokers.com.

Related MCP server: IBKR MCP Server

Tools

Read-only (always available):

• list_accounts, get_account_summary, get_positions, get_portfolio, get_pnl

• get_quote, get_historical_data, lookup_contract, search_contracts

• get_open_orders, get_executions

• review_positions — flags open positions past a loss threshold for a deliberate "thesis changed or just the price?" review

• get_trade_history, get_cash_transactions, get_history_coverage (see Historical activity)

Trading (only registered when IBKR_ENABLE_TRADING=true):

• preview_order — a what-if that returns margin and commission impact and places nothing

• place_order — market or limit orders, with quantity, notional, and rate caps

• cancel_order — cancels an open order (by default only orders this server placed)

Requirements

• uv for dependency management.

• TWS or IB Gateway, running and logged in, with the API enabled: Configure > Settings > API > "Enable ActiveX and Socket Clients". Keep "Read-Only API" checked unless you deliberately enable trading.

• Ports: TWS live 7496, TWS paper 7497, Gateway live 4001, Gateway paper 4002.

Install

git clone https://github.com/jgalea/ibkr-mcp.git
cd ibkr-mcp
uv sync --locked

Register with Claude Code (run from the cloned directory):

claude mcp add ibkr --env IBKR_PORT=4001 -- uv --directory "$(pwd)" run ibkr-mcp

Or with Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "ibkr": {
      "command": "uv",
      "args": ["--directory", "/path/to/ibkr-mcp", "run", "ibkr-mcp"],
      "env": { "IBKR_PORT": "4001" }
    }
  }
}

Configuration

Security model

Trading is gated in three independent layers:

• No order tools are registered unless IBKR_ENABLE_TRADING=true, so a client cannot call what does not exist.

• In read-only mode every account-mutating call in the underlying library is stubbed out inside the process, so no code path can transmit an order.

• TWS / Gateway's own "Read-Only API" setting rejects order requests at the gateway. Keep it checked unless you enable trading. (The library's readonly connect flag only skips fetching order state; it is not enforcement on its own.)

Other properties:

• Transport is stdio and pinned; it cannot be promoted to a network listener by an environment variable or a stray .env.

• The IB API protocol is cleartext TCP. Keep IBKR_HOST on localhost; tunnel over SSH if you must reach a remote gateway.

• Do not run with INFO/DEBUG logging: the HTTP client logs request URLs at INFO, and Flex request URLs carry your token.

• Tool output (account IDs, balances, positions) flows into whatever model your MCP host uses. Be deliberate about which host you connect.

When trading is enabled, test against a paper account (port 7497 / 4002) first, and keep TWS's precautionary order settings on.

Historical activity

The Gateway socket only exposes current-day executions. get_trade_history and get_cash_transactions pull full account history (trades, dividends, interest, deposits, fees) from IBKR's Flex Web Service over HTTPS, and cache it in a local SQLite archive (~/.ibkr-mcp/archive.db, owner-only) so rows never age out of the rolling Flex window.

One-time setup in Client Portal:

1. Performance & Reports > Flex Queries > new Activity Flex Query. Include the Trades and Cash Transactions sections, period "Last 365 Calendar Days", format XML. Note the numeric Query ID.

2. On the same page, under Flex Web Service Configuration, enable it and generate a token.

3. Store the token outside your config, for example in the macOS Keychain, then point the server at it:

Backfilling history older than 365 days

A Flex query reaches at most the trailing 365 days. To seed the archive with older history, export Activity Statements (Client Portal > Performance & Reports > Statements > Activity Statement, Custom Date Range, up to 365 days per file, Download CSV) and import them:

uv run python -m ibkr_mcp.importer /path/to/activity_statement.csv

Imports are deduplicated, so re-running is safe. get_history_coverage reports the archived span.

Development

uv run pytest
uv run ruff check src tests

Disclaimer

Not affiliated with or endorsed by Interactive Brokers. Provided as-is under the MIT license, with no warranty. You are responsible for any orders placed through it and for keeping the trading gates configured as you intend. Nothing here is investment advice.

License

MIT