<div align="center">

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.

</div>

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.

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

Variable	Default	Notes
IBKR_HOST	127.0.0.1	TWS / Gateway host
IBKR_PORT	7497	Match your TWS / Gateway mode
IBKR_CLIENT_ID	23	Unique per API client (must be ≥ 1)
IBKR_TIMEOUT	10	Connect and request timeout, seconds
IBKR_MARKET_DATA_TYPE	3	1 live, 2 frozen, 3 delayed, 4 delayed-frozen
IBKR_ENABLE_TRADING	unset	true / 1 / yes registers the order tools
IBKR_MAX_ORDER_QUANTITY	1000	Hard cap on units per order (ceiling 1,000,000)
IBKR_MAX_ORDER_VALUE	50000	Cap on order notional (ceiling 10,000,000). Exact for limit orders; for market orders it is checked against a pre-submit snapshot price, so a fast-moving fill can exceed it
IBKR_ORDERS_PER_MINUTE	6	Aggregate order rate limit across concurrent calls
IBKR_ALLOW_EXTERNAL_CANCEL	unset	true lets cancel_order cancel orders not placed by this server

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:

Variable	Notes
IBKR_FLEX_QUERY_ID	Numeric ID of your Activity Flex Query (or IBKR_FLEX_QUERY_IDS, comma-separated, for several)
IBKR_FLEX_TOKEN_CMD	A command whose stdout is the token, e.g. security find-generic-password -s ibkr-flex-token -w
IBKR_FLEX_TOKEN	The token itself (fallback; prefer IBKR_FLEX_TOKEN_CMD so it stays out of config files)

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