ibkr-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ibkr-mcp show my account summary"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Confirm connectivity and return IBKR server time. |
| List managed accounts visible to the current login. |
| Fetch account summary values such as cash, buying power, and margin. |
| List open positions across accessible accounts. |
| List currently open orders visible to the session. |
| Fetch execution reports with optional account, symbol, side, and time filters. |
| Search contracts by ticker or company name. |
| Resolve a partial contract definition into concrete IBKR contract details. |
| Fetch read-only historical bars for a contract. |
Related MCP server: IBKR MCP Server
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-mcpinstances from starting against the sameIBKR_HOST/IBKR_PORT/IBKR_CLIENT_IDcombination.You should still enable IBKR's own
Read-Only APIsetting 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:
Open the API settings page.
Enable
ActiveX and Socket Clients.Set the socket port to the value you want this server to use.
Enable
Read-Only APIif you want IBKR to enforce read-only access too.Allow
127.0.0.1or 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 buildUseful development commands:
npm run dev
npm run typecheckRun
IBKR_HOST=127.0.0.1 \
IBKR_PORT=4002 \
IBKR_CLIENT_ID=19191 \
npm startIBKR_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 |
|
| Hostname of the IBKR Gateway or TWS socket API endpoint. |
|
| Socket API port. |
|
| API client ID used when connecting to IBKR. |
|
| Request timeout for IBKR API calls. |
|
| Default account group for |
| conservative defaults | Optional comma-separated override for summary fields. |
Default account summary tags:
AccountType,NetLiquidation,TotalCashValue,SettledCash,BuyingPower,AvailableFunds,ExcessLiquidity,GrossPositionValue,InitMarginReq,MaintMarginReq,DayTradesRemainingMCP 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_executionsaccepts eithertimein raw IB format (YYYYMMDD HH:mm:ss) orsincein RFC3339 form, but not both.ibkr_search_contractsis useful for discovery;ibkr_contract_detailsis the better follow-up when you need a specific contract definition for downstream calls.For stock and option lookups, the server infers
SMARTas the default exchange when appropriate. For cash pairs, it infersIDEALPRO.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-mcpprocess 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.
Available Tools
9 toolsibkr_accountsARead-only
List managed IBKR accounts visible to the current Gateway login.
Inputs: no named parameters.
ibkr_account_summaryARead-only
Return account summary values such as net liquidation, cash, buying power, and margin.
Inputs: tags, group.
ibkr_contract_detailsBRead-only
Resolve an IBKR contract definition and return matching contract details.
Inputs: contract (required), limit.
ibkr_executionsBRead-only
Return execution reports using optional filters such as account, symbol, side, or time.
Inputs: side, time, since, symbol, +4 more.
ibkr_historical_barsARead-only
Fetch read-only historical bars for a contract from IBKR Gateway.
Inputs: contract (required), useRTH, barSize, formatDate, +3 more.
ibkr_open_ordersARead-only
List currently open orders visible to the Gateway session. This server does not place, modify, or cancel orders.
Inputs: no named parameters.
ibkr_positionsARead-only
List open positions across all accessible IBKR accounts.
Inputs: no named parameters.
ibkr_search_contractsARead-only
Search IBKR contracts by ticker or company name and return matching instrument descriptors.
Inputs: pattern (required), limit.
ibkr_statusARead-only
Confirm read-only connectivity to the configured IBKR Gateway session and return server time.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool maps to a distinct IBKR resource: accounts, positions, account summary, open orders, executions, contract search, contract details, historical bars, and gateway status. Even the two contract tools are clearly separated as discovery versus detail resolution.
All tools share a consistent lowercase ibkr_ prefix and mostly use noun-style resource names such as ibkr_positions and ibkr_account_summary. The one action-style name, ibkr_search_contracts, is a minor deviation from an otherwise predictable pattern.
Nine tools is a well-scoped size for a read-only IBKR integration. Each tool covers a distinct data need without redundant overlap or unnecessary extras.
The set covers the core read-only brokerage workflow: accounts, positions, summary, orders, executions, contract discovery, and historical bars. A real-time quote or market data snapshot tool would round it out, but this is a minor gap given the read-only orientation.
Related MCP Connectors
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Historical tick, order book and settlement data for Polymarket and Predict.fun crypto up/down markets, plus smart-money lists and backtest quotes, over a read-only MCP server.
JW3.ai remote MCP server for market reads and confirm-gated trading execution.
Hosted MCP server for MT4 and MT5: read accounts, prices and candles, and place or close orders.
Related MCP Servers
- FlicenseCqualityDmaintenanceAn MCP server that provides an interface for the Interactive Brokers API via the ib_async library. It enables users to manage accounts, access real-time and historical market data, and execute or monitor trades through TWS or IB Gateway.331-
- AlicenseNot gradedqualityDmaintenanceAn MCP server for Interactive Brokers, enabling account management, trading operations, and market data queries.8MIT
- AlicenseAqualityDmaintenanceRead-only MCP server for Interactive Brokers that exposes market data, positions, and account info as MCP tools.8MIT
- FlicenseBqualityDmaintenanceMCP server for Interactive Brokers via IB Gateway, enabling read access to account data and trading capabilities for paper accounts.11-