ibkr-mcp-server
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-server show my current positions"
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-server
MCP server that exposes Interactive Brokers via the TWS API as 14 tools: account reads, market data, contract resolution, and order placement.
Paper-by-default. Live trading requires explicit opt-in via IBKR_TRADING_MODE=live.
Prerequisites
TWS or IB Gateway running locally. Download from IBKR.
API enabled in TWS/Gateway: Configure → API → Settings
Check "Enable ActiveX and Socket Clients"
Uncheck "Read-Only API"
Socket port:
7497(paper) or7496(live) — defaults match this serverAdd
127.0.0.1to "Trusted IPs"
uv installed:
curl -LsSf https://astral.sh/uv/install.sh | sh
Related MCP server: IBKR TWS MCP Server
Install
git clone <this repo>
cd ibkr-mcp-server
uv syncConfigure
Copy .env.example and adjust as needed (or export the vars in your shell / MCP client config).
Register with Claude Code
Add to ~/.claude.json (or a per-project .mcp.json):
{
"mcpServers": {
"ibkr": {
"command": "uv",
"args": [
"--directory", "/absolute/path/to/ibkr-mcp-server",
"run", "ibkr-mcp-server"
],
"env": {
"IBKR_TRADING_MODE": "paper",
"IBKR_CLIENT_ID": "17"
}
}
}
}Tools
Tool | Purpose |
| Connection + mode + gateway info |
| Cash, net liq, buying power, margin |
| Open positions with market price enrichment |
| Account-level or per-position P&L |
| Today's fills (or since ISO timestamp) |
| IBKR symbol search |
| Resolve symbol → canonical contract with conid |
| Snapshot bid/ask/last/volume |
| OHLCV bars |
| Place MKT/LMT/STP/STP_LMT order |
| Entry + take-profit + stop-loss |
| Modify an existing open order |
| Cancel an open order |
| List currently open orders |
Safety
Mode gate: server reads
managedAccountson connect and verifies prefixes (DU*= paper,U*= live). On mismatch, all order tools are blocked.Audit log: every order placement / modification / cancellation is appended as a JSON line to
$IBKR_AUDIT_LOG(default~/.ibkr-mcp-server/audit.log).Read-only mode: set
IBKR_READONLY=1to disable all order tools.
Risk rails (v2)
Three additional rails apply to place_order, place_bracket_order, and modify_order. cancel_order and list_open_orders are intentionally not gated.
Notional caps. Per-order and daily-cumulative ceilings in USD. Mode-aware: paper and live have independent envs. Set to
unlimitedto disable an individual cap.Rate limit. Each gated tool has its own token bucket (capacity 10, refill 10/min). Hardcoded in v2.
Kill switch. If
IBKR_HALT_FILEexists, every gated tool returns{status:"rejected", error_code:"HALT", ...}immediately. Remove the file to re-enable.
Blocks are returned as data (same shape as IB-side rejections) and appended to the audit log. They do not raise.
get_quote now returns a data_type field: "live" | "delayed" | "delayed_frozen" | "frozen". The server calls ib.reqMarketDataType(3) on connect so weekend/out-of-hours quotes fall back to delayed data instead of returning nulls.
Env var | Default | Purpose |
|
| Per-order notional cap in paper (USD); |
|
| Per-order notional cap in live (USD); |
|
| Daily cumulative cap in paper; |
|
| Daily cumulative cap in live; |
|
| Path probed on every order; presence halts all order-mutating tools |
Testing
uv run pytest # unit tests (default)
IBKR_INTEGRATION_TESTS=1 uv run pytest -m integration # against a running paper gateway
uv run python scripts/smoke.py # manual end-to-end smokeAvailable Tools
14 toolscancel_orderC
Cancel an existing open order.
Inputs: order_id (required).
get_account_summaryD
Cash, net liquidation, buying power, margin.
Inputs: account.
get_executionsC
Today's fills (or since ISO timestamp).
Inputs: since.
get_historical_barsD
Historical OHLCV bars.
Inputs: symbol (required), use_rth, bar_size, currency, +6 more.
get_pnlC
Account-level or per-position P&L.
Inputs: conid, account.
get_positionsC
Open positions with market price enrichment.
Inputs: account.
get_quoteC
Snapshot bid/ask/last/volume.
Inputs: symbol (required), currency, exchange, sec_type, +1 more.
list_open_ordersC
List currently open orders.
Inputs: account.
modify_orderC
Modify an existing open order.
Inputs: order_id (required), quantity, stop_price, limit_price.
place_bracket_orderC
Place a bracket: entry + take-profit + stop-loss.
Inputs: action (required), symbol (required), quantity (required), entry_type (required), +9 more.
place_orderC
Place a single-leg market/limit/stop/stop-limit order.
Inputs: action (required), symbol (required), quantity (required), order_type (required), +9 more.
qualify_contractC
Resolve a symbol to a canonical contract with conid.
Inputs: symbol (required), currency, exchange, sec_type, +1 more.
search_symbolC
Search IBKR for symbols matching a query.
Inputs: query (required), sec_type.
statusA
Return connection state, trading mode, and gateway info.
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 14 tools
Each tool targets a distinct operation: order management (place, modify, cancel, list, bracket), data retrieval (account, positions, P&L, quotes, executions, historical bars), contract resolution (qualify, search), and connection status. No significant overlap.
All tools follow a consistent verb_noun pattern with snake_case (e.g., get_quote, place_order, list_open_orders). Naming is predictable and readable.
With 14 tools, the server is well-scoped for a trading API, covering orders, account info, market data, and contract resolution without being overloaded or sparse.
Core trading workflows are well-covered: full order lifecycle, account and position monitoring, market data, and contract lookup. Minor gaps like advanced order types or market depth are absent, but the essential surface is complete.
Related MCP Connectors
Unified financial infrastructure connecting AI agents directly to trade live/demo brokerage accounts, Web3 non-custodial wallets, real-time market data across equities, ETFs, crypto, forex, options, DeFi swaps, and prediction markets, institutional research feeds, and algorithmic strategy backtesters.
Agentic brokerage access to a US brokerage account: quotes, orders, positions, cash and documents.
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Connect brokerage accounts to AI assistants: holdings, orders, asset lookup, and approved trading.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables AI assistants to interact with Interactive Brokers trading accounts to retrieve market data, check positions, and place trades. Includes pre-configured IB Gateway and handles OAuth authentication automatically.14161 npm228MIT
- FlicenseNot gradedqualityDmaintenanceEnables LLM clients to interact with Interactive Brokers Trader Workstation for automated trading workflows. Supports market data retrieval, portfolio management, and order execution through the TWS API.5-
- FlicenseNot gradedqualityDmaintenanceEnables interaction with Interactive Brokers via the TWS API or IB Gateway to manage accounts, retrieve market data, and execute trades. It supports features like real-time market data, historical data queries, and order management for stocks and options.4-
- AlicenseAqualityDmaintenanceEnables AI agents to trade on Interactive Brokers: check quotes, balance, positions, and execute buy/sell orders (including fractional shares by dollar amount) via the Client Portal API.2015MIT