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 What's my portfolio P&L today?"
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.
What is this?
ibkr-mcp connects Claude (or any MCP-compatible AI) directly to your Interactive Brokers account through the Client Portal Web API. It's a thin, stateless wrapper — no session management, no gateway lifecycle, no tickling. Just tools that call the API.
Gateway authentication and session management is handled externally by IBeam, which runs in Docker and handles login automation + 2FA.
You: "What's my portfolio P&L today?"
Claude: Your account U1234567 is up $1,247.30 today.
Top winners: AAPL (+$523), NVDA (+$312)
Net liquidation: $284,521.00Related MCP server: IBKR MCP Server
Features
26 read-only tools — portfolio, market data, options, orders, scanner, watchlists, news, FX
Stateless — no session management, no tickling, no gateway lifecycle. IBeam handles all of that.
Human-readable market data — snapshot fields mapped to names like
lastPrice,week52High,sectorZero dependencies beyond
@modelcontextprotocol/sdkandzodRate limiting — per-endpoint sliding window that waits instead of erroring
Snapshot warmup — auto-retries on IB's first-call empty response
Quick Start
Prerequisites
Node.js 18+
Docker (for IBeam)
IB account with Client Portal API access
1. Start IBeam (Gateway + Auth)
IBeam handles the Client Portal Gateway process, browser login automation, session keepalive, and 2FA. See IBeam Setup below.
docker run -d \
--name ibeam \
-p 5000:5000 \
-e IBEAM_ACCOUNT=your_ib_username \
-e IBEAM_PASSWORD=your_ib_password \
-e IBEAM_GATEWAY_BASE_URL=https://localhost:5000 \
voyz/ibeam2. Install & Build MCP
git clone https://github.com/yigitabi5444/yigit_ibkr_mcp.git
cd yigit_ibkr_mcp
npm install
npm run build3. Add to Claude Desktop
{
"mcpServers": {
"ibkr": {
"command": "node",
"args": ["/path/to/yigit_ibkr_mcp/dist/index.js"],
"env": {
"IBKR_GATEWAY_URL": "https://localhost:5000"
}
}
}
}IBeam Setup
IBeam is the recommended way to run the IB Client Portal Gateway. It handles:
Starting the gateway Java process
Automated browser login (headless Chrome + Selenium)
2FA handling (push notification, SMS, or custom handler)
Session keepalive
Automatic re-authentication on session expiry
Basic Docker Setup
docker run -d \
--name ibeam \
--restart unless-stopped \
-p 5000:5000 \
-e IBEAM_ACCOUNT=your_username \
-e IBEAM_PASSWORD=your_password \
voyz/ibeamWith 2FA (Push Notification)
docker run -d \
--name ibeam \
--restart unless-stopped \
-p 5000:5000 \
-e IBEAM_ACCOUNT=your_username \
-e IBEAM_PASSWORD=your_password \
-e IBEAM_TWO_FA_HANDLER=PUSH \
voyz/ibeamDocker Compose
services:
ibeam:
image: voyz/ibeam
restart: unless-stopped
ports:
- "5000:5000"
environment:
IBEAM_ACCOUNT: ${IB_USERNAME}
IBEAM_PASSWORD: ${IB_PASSWORD}
IBEAM_TWO_FA_HANDLER: PUSHSee the IBeam docs for full configuration including custom 2FA handlers, health checks, and troubleshooting.
Tools
Account & Portfolio
Tool | Description |
| List all brokerage accounts |
| Curated: NLV, cash, buying power, margin, positions value, cash by currency |
| Full 70+ field raw summary |
| Asset class breakdown (stocks, options, futures, cash %) |
| All positions with P&L. Auto-paginates. Options include strike/right/expiry |
| Single position by contract ID |
| Historical NAV and time-weighted returns |
| Transaction log with filters |
Market Data
Tool | Description |
| Real-time quote with readable names (lastPrice, bid, ask, sector, week52High, etc.) |
| Historical OHLCV bars (1min to monthly, up to 5 years) |
Contracts
Tool | Description |
| Search by symbol or company name |
| Curated contract specs (trading hours, tick size, exchanges) |
| Stock contracts across exchanges |
| Non-expired futures by underlying |
Options
Tool | Description |
| Full option chain (composite: strikes + conids in one call) |
| Strike prices for a specific expiration |
Orders & Trades
Tool | Description |
| All currently working orders |
| Single order status |
| Execution history (7 days) |
Scanner
Tool | Description |
| Available scanner types and filters (cached 15min) |
| Market scanner (top gainers, most active, etc.) |
Other
Tool | Description |
| Saved watchlists |
| FX rates |
| Available news providers |
| Market briefing from Briefing.com |
| Session diagnostics |
Configuration
Environment Variable | Default | Description |
|
| Client Portal Gateway URL (IBeam default: 5000) |
| (auto-detected) | Default account ID |
|
| Request timeout in ms |
Architecture
┌─────────────────┐ stdio ┌────────────────┐ HTTPS ┌─────────────┐
│ Claude Desktop │ ◄────────────► │ ibkr-mcp │ ────────────► │ IBeam │
│ (MCP Client) │ │ (stateless) │ │ (Docker) │
└─────────────────┘ │ │ │ │
│ IBClient │ │ CP Gateway │
│ RateLimiter │ │ Selenium │
│ 26 Tools │ │ Keepalive │
└────────────────┘ └─────────────┘The MCP is intentionally thin — it just makes HTTP calls. IBeam owns the gateway process, authentication, session keepalive, and 2FA.
Development
npm run dev # Run with tsx (hot reload)
npm test # Unit tests (27 tests, mocked, no gateway needed)
npm run test:integration # Integration tests (requires live gateway)IBKR_GATEWAY_URL=https://localhost:5000 npm run test:integrationLicense
MIT
Available Tools
32 toolsget_account_allocationGet Account AllocationARead-only
Get asset class allocation breakdown showing distribution across stocks, options, futures, cash, bonds, etc. as percentages and values.
Inputs: accountId.
get_accountsGet AccountsARead-only
List all brokerage accounts with IDs and capabilities. Returns account IDs that can be used with other tools.
Inputs: no named parameters.
get_account_summaryGet Account SummaryARead-only
Get curated account summary: net liquidation, cash, buying power, margin, gross position value, P&L, and cash breakdown by currency. Returns the most important fields only — use get_account_summary_full for all 70+ fields.
Inputs: accountId.
get_account_summary_fullGet Account Summary (Full)ARead-only
Get the full raw account summary with all 70+ fields including segment-level duplicates (-s suffix). Use get_account_summary for a curated version.
Inputs: accountId.
get_auth_statusGet Auth StatusARead-only
Check if the Client Portal Gateway is authenticated. Returns auth state, competing session flag, and connection status.
Inputs: no named parameters.
get_contract_detailsGet Contract DetailsARead-only
Get full contract details for a known contract ID (conid). Returns exchange, currency, trading hours, tick size, and other specs.
Inputs: conid (required).
get_exchange_rateGet Exchange RateARead-only
Get the current exchange rate between two currencies. Requires brokerage session (auto-acquired, auto-releases after idle).
Inputs: source (required), target (required).
get_fundamentalsGet FundamentalsARead-only
Get company metadata for a stock: name, sector, sectorGroup, industry, listing exchange, country, currency, asset type, options availability, CUSIP. IBKR Client Portal API does NOT expose financial statements (balance sheet, income statement, cash flow), valuation ratios (P/E, market cap, EPS), or dividend data — those fields are deprecated by IBKR. For revenue/EPS growth %, 52-week range, sector/industry from market data, use get_market_snapshot. For OHLCV history, use get_price_history.
Inputs: conid (required).
get_futures_contractsGet Futures ContractsARead-only
Look up non-expired futures contracts by underlying symbol.
Inputs: symbols (required).
get_live_ordersGet Live OrdersARead-only
List all currently live/working orders. Requires brokerage session (auto-acquired, auto-releases after idle).
Inputs: no named parameters.
get_market_snapshotGet Market SnapshotARead-only
Get real-time market data snapshot with human-readable field names. Returns: symbol, lastPrice, bid, ask, volume, open, high, low, close, change, changePercent, week52High, week52Low, sector, industry, avgVolume, revenueGrowthPct, epsGrowthPct, changeFrom52wkHighPct, price bands (10d/30d). Also returns peRatio, eps, dividendYieldPct, marketCap, impliedVolatility when your IB market data subscription includes them. Auto-retries on first-call warmup.
Inputs: conids (required), fields.
get_news_briefingGet News BriefingARead-only
Get the latest market news briefing from Briefing.com. Returns a full market commentary/analysis article.
Inputs: no named parameters.
get_news_sourcesGet News SourcesARead-only
List available news sources/providers from IB.
Inputs: no named parameters.
get_option_chainGet Option ChainARead-only
Get available option expirations and strikes for an underlying security. Returns the list of strikes for calls and puts. Fast — single API call. To get conids for specific strikes, use get_option_contracts.
Inputs: conid (required), month, exchange.
get_option_contractsGet Option ContractsARead-only
Get option contract details (conids) for specific strikes. Returns conids you can use with get_market_snapshot for pricing/IV. Fetches up to 10 strikes at a time to stay fast.
Inputs: conid (required), month (required), strikes (required), right, +1 more.
get_option_strikesGet Option StrikesARead-only
Get available strike prices for options on an underlying security for a specific expiration month.
Inputs: conid (required), month (required), exchange.
get_order_statusGet Order StatusARead-only
Get detailed status of a specific order. Requires brokerage session (auto-acquired, auto-releases after idle).
Inputs: orderId (required).
get_performanceGet PerformanceARead-only
Get historical account performance including NAV and time-weighted returns over a configurable period.
Inputs: period (required), accountIds (required).
get_pnlGet P&LARead-only
Get account-level profit and loss data: daily P&L (dpl), unrealized P&L (upl), net liquidity (nl), and excess liquidity (el). Requires brokerage session (auto-acquired, auto-releases after idle).
Inputs: accountId.
get_position_by_conidGet Position by Contract IDARead-only
Get a specific position by contract ID (conid). Returns position details including quantity, avg cost, market value, unrealized P&L, and daily P&L.
Inputs: conid (required), accountId.
get_positionsGet PositionsARead-only
Get all open positions for an account. Auto-paginates through all pages. Returns stocks, options, futures, etc. Each position includes: symbol, quantity, avg cost, market value, unrealized P&L, daily P&L. Option positions also include: strike, right (C/P), expiry, multiplier.
Inputs: accountId.
get_price_historyGet Price HistoryARead-only
Get historical OHLCV price bars for a contract. Supports various periods and bar sizes. Requires brokerage session (auto-acquired, auto-releases after idle).
Inputs: bar (required), conid (required), period (required), exchange, +1 more.
get_scanner_paramsGet Scanner ParametersARead-only
Get available market scanner parameters. Cached for 15 minutes. Requires brokerage session (auto-acquired, auto-releases after idle).
Inputs: no named parameters.
get_stock_contractsGet Stock ContractsARead-only
Look up stock contracts by symbol across all exchanges. Returns available contract variants with exchange and conid.
Inputs: symbols (required).
get_tradesGet TradesARead-only
Get trade execution history (current day + 6 previous days). Requires brokerage session (auto-acquired, auto-releases after idle).
Inputs: no named parameters.
get_transaction_historyGet Transaction HistoryCRead-only
Get transaction history for accounts with optional filters.
Inputs: accountIds (required), days, type, currency.
get_watchlistGet WatchlistARead-only
Get contracts in a specific watchlist by ID. Requires brokerage session (auto-acquired, auto-releases after idle).
Inputs: id (required).
get_watchlistsGet WatchlistsARead-only
List saved watchlists. Requires brokerage session (auto-acquired, auto-releases after idle).
Inputs: no named parameters.
ping_sessionPing SessionARead-only
Send a tickle/keepalive to the Client Portal Gateway.
Inputs: no named parameters.
reauthenticateReauthenticateBRead-only
Trigger re-authentication of the Client Portal Gateway session.
Inputs: no named parameters.
run_scannerRun ScannerARead-only
Execute a market scanner to find securities matching specific criteria. Requires brokerage session (auto-acquired, auto-releases after idle).
Inputs: type (required), location (required), instrument (required), filters.
search_contractsSearch ContractsARead-only
Search for securities by symbol or company name. Returns contract IDs (conids), symbol, exchange, security type, and description. Use the returned conid with other tools.
Inputs: symbol (required), isName, secType.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
The tools are mostly distinct with clear purposes, though account summary variants and multiple option lookup tools (get_option_chain, get_option_contracts, get_option_strikes) could cause initial confusion. Descriptions are detailed enough to disambiguate.
Most tools use a get_* verb_noun pattern, but a few like reauthenticate, ping_session, run_scanner, and search_contracts break the uniformity. All names are snake_case and readable, but the mix of get_ and action verbs is a minor inconsistency.
With 32 tools, the count exceeds the 25+ threshold and feels heavy. While IBKR is a broad domain, many tools could be consolidated (e.g., account summary variants), making the surface area larger than necessary.
The tool set covers account, market data, scanner, watchlist, and news, but critically lacks order placement, modification, or cancellation. Without these, the server cannot perform actual trading, which is a core expectation for a brokerage MCP.
Maintenance
Related MCP Connectors
Connect brokerage accounts to AI assistants: holdings, orders, asset lookup, and approved trading.
Read-only access to your MetaTrader 4 and 5 accounts for AI agents: balances, open positions, trade history with win rate, live quotes, symbol specs and candles. It cannot place, modify or close orders.
Agentic brokerage access to a US brokerage account: quotes, orders, positions, cash and documents.
Read-only access to your own bank, card and brokerage accounts for Claude, ChatGPT and other AI agents: balances, transactions, spending, subscriptions, cashflow and investment holdings. It can never move money.
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
- AlicenseNot gradedqualityDmaintenanceProvides AI models with secure access to Interactive Brokers trading data and functionality, enabling account management, market data retrieval, and trading operations through natural language interactions.18MIT
- FlicenseNot gradedqualityDmaintenanceConnects AI assistants to Interactive Brokers for intelligent portfolio management, options analysis, risk monitoring, and automated trading strategy suggestions. Enables real-time account tracking, Greeks calculations, option chain analysis, and playbook-based risk adjustments through natural language.5-
- AlicenseNot gradedqualityBmaintenanceEnables read-only access to Interactive Brokers data including contracts, market data, news, fundamentals, and portfolio/account information for LLM workflows and autonomous agents.19BSD 3-Clause