ibkr-mcp

ibkr-mcp

ibkr-mcp is a read-only MCP server for Interactive Brokers IBKR Gateway or TWS. It connects to an already running socket API session and exposes account, contract, execution, and historical-data queries to MCP clients over stdio.

The server does not implement any order-entry operations. There are no tools for placing, modifying, or cancelling orders.

What It Exposes

| Tool | Purpose | | --- | --- | | ibkr_status | Confirm connectivity and return IBKR server time. | | ibkr_accounts | List managed accounts visible to the current login. | | ibkr_account_summary | Fetch account summary values such as cash, buying power, and margin. | | ibkr_positions | List open positions across accessible accounts. | | ibkr_open_orders | List currently open orders visible to the session. | | ibkr_executions | Fetch execution reports with optional account, symbol, side, and time filters. | | ibkr_search_contracts | Search contracts by ticker or company name. | | ibkr_contract_details | Resolve a partial contract definition into concrete IBKR contract details. | | ibkr_historical_bars | Fetch read-only historical bars for a contract. |

Safety Model

• Every registered MCP tool is read-only.
• The server never calls IBKR APIs for order placement, modification, or cancellation.
• A local process lock prevents duplicate ibkr-mcp instances from starting against the same IBKR_HOST / IBKR_PORT / IBKR_CLIENT_ID combination.
• You should still enable IBKR's own Read-Only API setting if you want Gateway- or TWS-level enforcement as a second guardrail.

Prerequisites

• Node.js and npm
• A running IBKR Gateway or TWS session
• Socket API access enabled in that IBKR session

In IBKR Gateway or TWS:

1. Open the API settings page.
2. Enable ActiveX and Socket Clients.
3. Set the socket port to the value you want this server to use.
4. Enable Read-Only API if you want IBKR to enforce read-only access too.
5. Allow 127.0.0.1 or your MCP host in trusted IPs if your IBKR configuration requires it.

The server default is IBKR_PORT=4002, which matches the common IBKR Gateway paper-trading setup. If your session uses a different port, set IBKR_PORT explicitly.

Install

npm install
npm run build

Useful development commands:

npm run dev
npm run typecheck

Run

IBKR_HOST=127.0.0.1 \
IBKR_PORT=4002 \
IBKR_CLIENT_ID=19191 \
npm start

IBKR_CLIENT_ID must be unique for the API client session you want to open. Run exactly one ibkr-mcp process per IBKR_HOST / IBKR_PORT / IBKR_CLIENT_ID.

If your MCP client launches this server for you, do not also leave a separate npm start process running against the same target. The server will fail fast if another instance already holds the same lock.

Configuration

| Variable | Default | Description | | --- | --- | --- | | IBKR_HOST | 127.0.0.1 | Hostname of the IBKR Gateway or TWS socket API endpoint. | | IBKR_PORT | 4002 | Socket API port. | | IBKR_CLIENT_ID | 19191 | API client ID used when connecting to IBKR. | | IBKR_TIMEOUT_MS | 10000 | Request timeout for IBKR API calls. | | IBKR_ACCOUNT_GROUP | All | Default account group for ibkr_account_summary. | | IBKR_ACCOUNT_SUMMARY_TAGS | conservative defaults | Optional comma-separated override for summary fields. |

Default account summary tags:

AccountType,NetLiquidation,TotalCashValue,SettledCash,BuyingPower,AvailableFunds,ExcessLiquidity,GrossPositionValue,InitMarginReq,MaintMarginReq,DayTradesRemaining

MCP Configuration Example

Point your MCP client at the built server entrypoint:

{
  "mcpServers": {
    "ibkr": {
      "command": "node",
      "args": ["/absolute/path/to/ibkr-mcp/dist/index.js"],
      "env": {
        "IBKR_HOST": "127.0.0.1",
        "IBKR_PORT": "4002",
        "IBKR_CLIENT_ID": "19191"
      }
    }
  }
}

This project uses stdio transport. That means each MCP client normally starts its own server process. If you need multiple clients to share one IBKR session, move to a shared daemon or network transport rather than launching separate stdio instances.

Usage Notes

• ibkr_executions accepts either time in raw IB format (YYYYMMDD HH:mm:ss) or since in RFC3339 form, but not both.
• ibkr_search_contracts is useful for discovery; ibkr_contract_details is the better follow-up when you need a specific contract definition for downstream calls.
• For stock and option lookups, the server infers SMART as the default exchange when appropriate. For cash pairs, it infers IDEALPRO.
• Historical data, executions, and some contract lookups still depend on the permissions attached to the logged-in IBKR user.

Troubleshooting

• Connection failures usually mean the IBKR session is not running, the socket API is disabled, the port is wrong, or the client ID is already in use.
• Duplicate-process errors mean another ibkr-mcp process is already running with the same host, port, and client ID combination.
• Empty or incomplete market-data responses often point to IBKR permissions, exchange entitlements, or an underspecified contract.
• This server does not launch IBKR Gateway or TWS. It only connects to an existing API endpoint.