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.
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.
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
IB Gateway or Trader Workstation (TWS) running on localhost (default port 4001)
Python 3.11+
An active IBKR account (paper or live)
git clone https://github.com/mark-liu/ibkr-mcp.git
cd ibkr-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .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 |
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.
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 | — |
URI | Description |
| Current positions as context |
| Account summary as context |
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 to None before 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.
pip install -e ".[dev]"
pytest tests/ -vTests run without a live IB Gateway — all IB interactions are mocked.
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_statusThis 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 switching
jeffbai996/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.
MIT
Get account summary: net liquidation, cash, margin, buying power, P&L.
Returns key account metrics grouped by currency.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description mentions that metrics are grouped by currency, which adds behavioral context. However, it does not explicitly state read-only nature or any potential side effects, though implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-loaded with key info. No extraneous content. Efficiently communicates purpose and output structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, description does not need to detail return format. Lists key metrics and mentions grouping by currency, which is sufficient for this zero-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. Description adds no parameter details but is not needed; baseline score for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get account summary' and lists specific metrics (net liquidation, cash, margin, buying power, P&L). Differentiates from siblings like ibkr_positions or ibkr_quote.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicit usage context is clear as a read operation for overall account health. Does not explicitly state when to use alternatives, but sibling tool names provide sufficient differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check IB Gateway connection health and configuration.
Returns connection state, managed accounts, market data type, market hours status, and cache statistics.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It discloses the return values (connection state, managed accounts, market data type, etc.), indicating a read-only diagnostic operation. However, it does not explicitly state that it is non-destructive or that no side effects occur, though this is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear sentences with no extraneous information. The purpose is front-loaded, and the return values are efficiently listed. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no annotations, but with an output schema (not shown), the description sufficiently covers the tool's behavior and return content. It lists five key return items, likely matching the schema, making it complete for a connection status check.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. The description adds no parameter info (unnecessary). Baseline is 4 for zero-parameter tools, and the description does not detract from this.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool checks IB Gateway connection health and configuration, using a specific verb and resource. It distinguishes itself from sibling tools like ibkr_account_summary and ibkr_contract_search which focus on different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, nor any exclusion criteria. The description only states its purpose, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for contracts by name or symbol using IB's fuzzy matching.
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | Yes | Search text (e.g. "Apple", "AAPL", "Bitcoin") |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry the full burden. It mentions 'fuzzy matching' which hints at behavior, but does not disclose outcomes on failure, read-only nature, or any rate limits. No contradictions with annotations (none exist).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, efficient sentence of 13 words. No unnecessary text, front-loaded with key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and simple single-parameter tool, the description is mostly complete. However, it could hint that output contains contract identifiers needed by sibling tools, which would aid agent reasoning.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a single parameter 'pattern' already described with examples. The description adds little beyond restating that search is by name or symbol; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Search for contracts by name or symbol using IB's fuzzy matching', specifying verb (search), resource (contracts), and method (fuzzy matching). This distinguishes it from sibling tools like ibkr_quote or ibkr_option_chain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The implied usage is to find contract IDs, but no explicit guidance on when to use this vs alternatives like ibkr_quote or ibkr_option_chain is provided. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get live FX rate for a currency pair.
| Name | Required | Description | Default |
|---|---|---|---|
| pair | Yes | Currency pair like "EURUSD", "AUDUSD", "USDJPY" |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must stand alone. It correctly implies a safe read operation, but lacks details on rate limiting, connection requirements, or data freshness. While not misleading, it is minimally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that efficiently conveys the tool's purpose with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers the basics. However, it lacks usage context and behavioral details that would enhance agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter is already described in the schema. The description adds no extra meaning beyond the schema's explanation of the currency pair format. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves a live FX rate for a currency pair. The specific resource and action are unambiguous, and the tool is well-distinguished from siblings like ibkr_quote which targets securities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., ibkr_quote) or under what conditions it is appropriate. The agent is left without context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get OHLCV historical bars for a symbol.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Ticker symbol (e.g. "AAPL", "SPY") | |
| use_rth | No | Regular trading hours only (default true) | |
| bar_size | No | Bar size: "1 min", "5 mins", "1 hour", "1 day", "1 week" | 1 day |
| duration | No | Lookback period in IB format: "1 D", "1 W", "1 M", "1 Y" | 1 M |
| what_to_show | No | Data type: "TRADES", "MIDPOINT", "BID", "ASK" | TRADES |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but discloses no behavioral traits: no mention of rate limits, data freshness, required connection state, error handling, or whether data is adjusted. The single sentence provides no behavioral context beyond the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, efficiently conveying the core function without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and full schema coverage, the description adequately states the primary purpose. It could hint at output structure or supported exchanges, but is sufficient for a straightforward data retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters comprehensively. The main description adds no additional meaning beyond what the schema provides, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'OHLCV historical bars' for a symbol, making the tool's purpose immediately clear. It distinguishes this historical data tool from siblings like ibkr_quote (current price) and ibkr_option_chain (options data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. Missing advice on choosing bar_size, duration, or what_to_show parameters, nor any indication of prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Underlying symbol (e.g. "AAPL", "FCX") | |
| exchange | No | Optional exchange filter (empty = all exchanges) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return content (chain structure, not Greeks) but does not mention whether it is read-only, any rate limits, or data freshness. While clear, it could add more behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three sentences. It front-loads the purpose, then clarifies limitations and alternatives. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters and an output schema (implied), the description adequately covers what the tool returns and its scope. It explicitly states what is not returned, which prevents misuse. The guidance is sufficient for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description mentions 'symbol' but does not add meaning beyond the schema's description. The exchange parameter is not mentioned in the description, but the schema already documents it. Minimal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves available option expirations and strikes for a symbol, specifies the return type (chain structure), and distinguishes itself from ibkr_quote by explicitly stating what it does not provide (Greeks). This effectively differentiates it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: use for obtaining chain structure; for Greeks, use ibkr_quote with specific option symbols. This tells the agent when to use this tool and when to use an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all portfolio positions with P&L, market value, and weight %.
Returns positions sorted by absolute market value (largest first).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions sorting by absolute market value (largest first), which is helpful, but lacks information about authentication, rate limits, or behavior when no positions exist. Some transparency but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The first sentence states the purpose, the second adds a key behavioral detail (sorting). Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an output schema, the description provides sufficient information about what the tool returns and its sorting behavior. No additional context seems necessary for a straightforward read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description adds meaning beyond the empty schema by explaining the return data (positions with P&L, market value, weight %) and sorting, which is valuable context for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'portfolio positions', and specifies returned fields (P&L, market value, weight %) and sorting behavior. This distinguishes it from sibling tools like ibkr_account_summary and ibkr_quote.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for viewing positions but does not explicitly state when to use this tool versus alternatives like ibkr_account_summary, nor does it mention when not to use it. No exclusions or contextual cues provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current price quotes for one or more symbols.
| Name | Required | Description | Default |
|---|---|---|---|
| symbols | Yes | Comma or space separated symbols (max 20). Example: "AAPL MSFT" or "SPY,QQQ" |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description indicates a read operation, which is appropriate for a quote tool. However, with no annotations, it fails to provide additional behavioral context such as rate limits or authentication requirements. The simplicity of the tool mitigates this somewhat.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, concise sentence that conveys the essential function without unnecessary words. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the straightforward nature of the tool, the description is largely complete. Could be slightly improved by noting the absence of authentication details, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already provides detailed description for the 'symbols' parameter including format and example. The description does not add additional semantics beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's action ('Get') and resource ('current price quotes'). It is distinct from sibling tools like ibkr_account_summary or ibkr_connection_status, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No mention of use cases, prerequisites, or scenarios where other tools might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0ibkr_account_summaryibkr_connection_statusibkr_contract_searchibkr_fx_rateibkr_historical_barsibkr_option_chainibkr_positionsibkr_quoteScored 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.
MCP server for OpenMM — exposes market data, account, trading, and strategy tools to AI agents
MCP server exposing the Backtest360 engine API as tools for AI agents.
Hosted MCP for stocks, options, Greeks, brokers, order previews, alerts, and workflows.
MCP server with quote and live cryptocurrency price tools, local and cloud-deployed transports.
