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 portfolio 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
Read-only MCP server for Interactive Brokers Gateway via the TWS socket API. Connects directly to your running IB Gateway on localhost — no Client Portal REST API, no bundled Java gateway, no 264 MB npm packages.
What it does
Exposes IB Gateway market data, positions, and account info as MCP tools that any MCP client (Claude Code, Claude Desktop, etc.) can call.
Read-only by design. No order placement tools. The connection uses readonly=True at the API level — IB Gateway will reject order submissions even if the code is modified.
Related MCP server: IBKR MCP Server
Prerequisites
IB Gateway or Trader Workstation (TWS) running on localhost (default port 4001)
Python 3.11+
An active IBKR account (paper or live)
Installation
git clone https://github.com/mark-liu/ibkr-mcp.git
cd ibkr-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .Configuration
All configuration is via environment variables:
Variable | Default | Description |
|
| Gateway host |
|
| Gateway port (4001=live, 4002=paper) |
|
| API client ID (must be unique per connection) |
|
| 1=live, 2=frozen, 3=delayed, 4=frozen-delayed |
|
| Seconds between reconnect attempts |
|
| Contract cache TTL in seconds |
Claude Code Integration
Add to ~/.claude.json:
{
"mcpServers": {
"ibkr": {
"command": "/path/to/ibkr-mcp/.venv/bin/python",
"args": ["-m", "ibkr_mcp"],
"env": {
"IB_PORT": "4001",
"IB_CLIENT_ID": "10"
}
}
}
}Then in Claude Code, tools like ibkr_quote, ibkr_positions, ibkr_historical_bars become available automatically.
Available Tools
Tool | Description | Key Parameters |
| Current price quotes |
|
| OHLCV historical bars |
|
| Portfolio positions with P&L | — |
| NLV, cash, margin, buying power | — |
| Available expirations and strikes |
|
| Fuzzy search for contracts |
|
| Live FX rate |
|
| Gateway health check | — |
MCP Resources
URI | Description |
| Current positions as context |
| Account summary as context |
Design Decisions
TWS socket API, not Client Portal REST. Direct connection to IB Gateway on port 4001 via
ib_async. Sub-millisecond local latency, streaming-capable, full options support. No HTTP indirection through a Java gateway.Persistent connection with background reconnect. If IB Gateway restarts, the server automatically reconnects without manual intervention.
Contract caching. Qualified contracts (with populated
conId) are cached for 1 hour, eliminating redundant API round-trips.Market hours detection. Uses
exchange_calendars(NYSE) to automatically switch between live (type 1) and delayed (type 3) market data.NaN handling. IB returns
float('nan')for missing data. Every numeric field is cleaned toNonebefore JSON serialization.Rate limiting. Token bucket limiters respect IB's API limits: 45 req/s for market data, 1 req/s for historical data.
Graceful degradation. Response cache stores last-known-good data, so tools return stale results (flagged) instead of errors during brief disconnects.
Running Tests
pip install -e ".[dev]"
pytest tests/ -vTests run without a live IB Gateway — all IB interactions are mocked.
Project Structure
src/ibkr_mcp/
__init__.py
__main__.py # Entry point (nest_asyncio + mcp.run)
server.py # FastMCP server, lifespan, tool registration, resources
client.py # IBKRClient: connection, caching, all data methods
config.py # Environment variable configuration
cache.py # Contract cache + response cache
models.py # Pydantic input validation
utils.py # NaN handling, rate limiter, retry, formatting
tools/
market.py # ibkr_quote, ibkr_historical_bars, ibkr_fx_rate
account.py # ibkr_positions, ibkr_account_summary
options.py # ibkr_option_chain
search.py # ibkr_contract_search
status.py # ibkr_connection_statusAcknowledgments
This project was built after evaluating six existing IBKR MCP servers. While none were suitable as-is (wrong API, security issues, proprietary licenses, abandoned), each contributed patterns and lessons:
xiao81/IBKR-MCP-Server (Apache-2.0) — FastMCP lifespan pattern with typed context, MCP resources for portfolio/account data
ArjunDivecha/ibkr-mcp-server (MIT) — Rate limiting and retry decorator patterns, symbol validation approach, exception hierarchy design
omdv/ibkr-mcp-server — Market hours detection via
exchange_calendars, contract caching concept, market data type switchingjeffbai996/ibkr-terminal — Background reconnect loop concept, cached degradation pattern, NaN handling throughout, subscription cleanup patterns
code-rabi/interactive-brokers-mcp (MIT) — Tool definition and registration patterns, read-only mode enforcement approach
rcontesti/IB_MCP (MIT) — Endpoint categorization and tool description patterns
No code was copied from any of these projects. All implementations are original.
License
MIT
Available Tools
8 toolsibkr_account_summaryA
Get account summary: net liquidation, cash, margin, buying power, P&L.
Returns key account metrics grouped by currency.
Inputs: no named parameters. Returns: result
ibkr_connection_statusA
Check IB Gateway connection health and configuration.
Returns connection state, managed accounts, market data type, market hours status, and cache statistics.
Inputs: no named parameters. Returns: result
ibkr_contract_searchA
Search for contracts by name or symbol using IB's fuzzy matching.
Inputs: pattern (required). Returns: result
ibkr_fx_rateA
Get live FX rate for a currency pair.
Inputs: pair (required). Returns: result
ibkr_historical_barsB
Get OHLCV historical bars for a symbol.
Inputs: symbol (required), use_rth, bar_size, duration, +1 more. Returns: result
ibkr_option_chainA
Get available option expirations and strikes for a symbol.
Returns the chain structure (what expirations and strikes exist), not Greeks for individual contracts. Use ibkr_quote with specific option symbols for Greeks.
Inputs: symbol (required), exchange. Returns: result
ibkr_positionsA
Get all portfolio positions with P&L, market value, and weight %.
Returns positions sorted by absolute market value (largest first).
Inputs: no named parameters. Returns: result
ibkr_quoteA
Get current price quotes for one or more symbols.
Inputs: symbols (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a clearly distinct purpose: account summary, connection status, contract search, FX rate, historical bars, option chain, positions, and quotes. No ambiguity between tools; even similar tools like ibkr_fx_rate and ibkr_quote are differentiated by target (currency pair vs any symbol).
All tool names follow a consistent pattern: 'ibkr_' prefix followed by a descriptive snake_case noun phrase (e.g., account_summary, connection_status, fx_rate). No mixing of conventions, making the set predictable.
8 tools is well-scoped for a financial data and account server. It covers essential areas (account, connection, market data, positions) without being bloated. Each tool serves a clear purpose.
The tool set covers account info, market data, and portfolio positions but lacks order management (place, modify, cancel orders) which is a significant gap for a trading-related server. Core data retrieval is present but trading actions are missing.
Maintenance
Related MCP Connectors
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
MCP server for OpenMM — exposes market data, account, trading, and strategy tools to AI agents
JW3.ai remote MCP server for market reads and confirm-gated trading execution.
MCP server exposing the Backtest360 engine API as tools for AI agents.
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
- AlicenseNot gradedqualityDmaintenanceMCP server for Interactive Brokers that exposes portfolio data, market quotes, trading, and analysis to any MCP-compatible AI client, with support for EU investors and safety-gated trading.1MIT
- AlicenseAqualityDmaintenanceA read-only MCP server that connects to Interactive Brokers Gateway or TWS to expose account, contract, execution, and historical-data queries over stdio.915 npmMIT