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.