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

Related MCP server: ib-async-mcp

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

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.