Click on "Install 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 me 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.
A read-only-by-default MCP server for Interactive Brokers — account, positions, PnL, market data, and full trade history from a local TWS / IB Gateway session.
ibkr-mcp exposes your Interactive Brokers account to any Model Context Protocol client (Claude Code, Claude Desktop, and others) through a locally running Trader Workstation or IB Gateway, using the ib_async library.
No credentials pass through this server. You log in to TWS or IB Gateway as usual, and ibkr-mcp attaches to its API socket on 127.0.0.1. By default it is read-only: no order tools exist, and the only outbound network call it can make is the optional Flex history fetch, pinned to interactivebrokers.com.
Related MCP server: IBKR MCP Server
Read-only (always available):
list_accounts, get_account_summary, get_positions, get_portfolio, get_pnl
get_quote, get_historical_data, lookup_contract, search_contracts
get_open_orders, get_executions
review_positions — flags open positions past a loss threshold for a deliberate "thesis changed or just the price?" review
get_trade_history, get_cash_transactions, get_history_coverage (see Historical activity)
Trading (only registered when IBKR_ENABLE_TRADING=true):
preview_order — a what-if that returns margin and commission impact and places nothing
place_order — market or limit orders, with quantity, notional, and rate caps
cancel_order — cancels an open order (by default only orders this server placed)
uv for dependency management.
TWS or IB Gateway, running and logged in, with the API enabled: Configure > Settings > API > "Enable ActiveX and Socket Clients". Keep "Read-Only API" checked unless you deliberately enable trading.
Ports: TWS live 7496, TWS paper 7497, Gateway live 4001, Gateway paper 4002.
git clone https://github.com/jgalea/ibkr-mcp.git
cd ibkr-mcp
uv sync --lockedRegister with Claude Code (run from the cloned directory):
claude mcp add ibkr --env IBKR_PORT=4001 -- uv --directory "$(pwd)" run ibkr-mcpOr with Claude Desktop, in claude_desktop_config.json:
{
"mcpServers": {
"ibkr": {
"command": "uv",
"args": ["--directory", "/path/to/ibkr-mcp", "run", "ibkr-mcp"],
"env": { "IBKR_PORT": "4001" }
}
}
}Variable | Default | Notes |
|
| TWS / Gateway host |
|
| Match your TWS / Gateway mode |
|
| Unique per API client (must be ≥ 1) |
|
| Connect and request timeout, seconds |
|
| 1 live, 2 frozen, 3 delayed, 4 delayed-frozen |
| unset |
|
|
| Hard cap on units per order (ceiling 1,000,000) |
|
| Cap on order notional (ceiling 10,000,000). Exact for limit orders; for market orders it is checked against a pre-submit snapshot price, so a fast-moving fill can exceed it |
|
| Aggregate order rate limit across concurrent calls |
| unset |
|
Trading is gated in three independent layers:
No order tools are registered unless IBKR_ENABLE_TRADING=true, so a client cannot call what does not exist.
In read-only mode every account-mutating call in the underlying library is stubbed out inside the process, so no code path can transmit an order.
TWS / Gateway's own "Read-Only API" setting rejects order requests at the gateway. Keep it checked unless you enable trading. (The library's readonly connect flag only skips fetching order state; it is not enforcement on its own.)
Other properties:
Transport is stdio and pinned; it cannot be promoted to a network listener by an environment variable or a stray .env.
The IB API protocol is cleartext TCP. Keep IBKR_HOST on localhost; tunnel over SSH if you must reach a remote gateway.
Do not run with INFO/DEBUG logging: the HTTP client logs request URLs at INFO, and Flex request URLs carry your token.
Tool output (account IDs, balances, positions) flows into whatever model your MCP host uses. Be deliberate about which host you connect.
When trading is enabled, test against a paper account (port 7497 / 4002) first, and keep TWS's precautionary order settings on.
The Gateway socket only exposes current-day executions. get_trade_history and get_cash_transactions pull full account history (trades, dividends, interest, deposits, fees) from IBKR's Flex Web Service over HTTPS, and cache it in a local SQLite archive (~/.ibkr-mcp/archive.db, owner-only) so rows never age out of the rolling Flex window.
One-time setup in Client Portal:
Performance & Reports > Flex Queries > new Activity Flex Query. Include the Trades and Cash Transactions sections, period "Last 365 Calendar Days", format XML. Note the numeric Query ID.
On the same page, under Flex Web Service Configuration, enable it and generate a token.
Store the token outside your config, for example in the macOS Keychain, then point the server at it:
Variable | Notes |
| Numeric ID of your Activity Flex Query (or |
| A command whose stdout is the token, e.g. |
| The token itself (fallback; prefer |
A Flex query reaches at most the trailing 365 days. To seed the archive with older history, export Activity Statements (Client Portal > Performance & Reports > Statements > Activity Statement, Custom Date Range, up to 365 days per file, Download CSV) and import them:
uv run python -m ibkr_mcp.importer /path/to/activity_statement.csvImports are deduplicated, so re-running is safe. get_history_coverage reports the archived span.
uv run pytest
uv run ruff check src testsNot affiliated with or endorsed by Interactive Brokers. Provided as-is under the MIT license, with no warranty. You are responsible for any orders placed through it and for keeping the trading gates configured as you intend. Nothing here is investment advice.
Account summary: net liquidation, cash, buying power, margin, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Account ID; empty for all accounts |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It implies a read operation (get) but does not explicitly state side effects, authentication needs, or rate limits. However, the simple retrieval nature is clear from the 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?
Very concise, but lacks a verb and follows a list-like structure. Could be more structured, e.g., 'Retrieve account summary including...'.
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 simple retrieval tool with one parameter and an output schema, the description is minimally complete. It lacks usage guidance but covers the main return data.
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% (account parameter described). The description adds no extra meaning beyond the schema; it does not mention parameters or their behavior.
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 returns an account summary with specific financial fields like net liquidation, cash, buying power, etc. It differentiates from sibling tools by focusing on a high-level overview rather than specific transactions or positions.
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. The description does not mention prerequisites, context, or when not to use it, which is a gap given the number of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Historical cash activity (dividends, interest, deposits/withdrawals, fees) from the configured Flex query. Needs IBKR_FLEX_QUERY_ID + token; see README.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| max_rows | No | ||
| type_filter | No | Filter: Dividends, Withholding Tax, Deposits/Withdrawals, Broker Interest Received, Other Fees; empty for all |
| 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 burden of behavioral disclosure. It notes the data source ('from the configured Flex query') and prerequisites, which are critical for correct invocation. However, it does not mention whether the tool is read-only, has side effects, or handles errors gracefully.
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 two sentences with no redundancy. The first sentence summarizes the tool's purpose, and the second adds a crucial prerequisite. It is concise, though it could front-load the prerequisite for quicker parsing.
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 three parameters and no annotations, the description is incomplete. It mentions the data source and prerequisites but does not clarify pagination behavior (despite max_rows), default behavior for days=0, or output format (though an output schema exists). The reference to README is insufficient.
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 low (33%), so the description should compensate. It lists cash activity types that map to type_filter, but does not explain days or max_rows beyond what the schema provides. The description adds minimal useful parameter context.
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 tool fetches 'Historical cash activity' and lists examples (dividends, interest, deposits/withdrawals, fees), distinguishing it from siblings like get_executions or get_trade_history. However, the verb 'get' is only implied by the name, not explicitly stated in the description.
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 lacks any guidance on when to use this tool versus alternatives. It only mentions prerequisites ('Needs IBKR_FLEX_QUERY_ID + token') but does not compare with sibling tools or specify conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Executions (fills) from the current session/day.
| 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, so description carries full burden. It reveals temporal scope and that executions are fills, but lacks details on authorization requirements, data freshness, or whether partial fills are included. Acceptable for a simple read tool but not comprehensive.
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 sentence with no waste. Front-loaded with the core purpose. Perfectly concise for a tool with no parameters.
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 has no parameters, a simple temporal constraint, and an output schema exists (so return values need no explanation), the description covers all necessary context for an agent to invoke it correctly.
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% (trivially). Description adds no parameter info because none is needed. Baseline 4 for zero-parameter tools.
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?
Clearly states the tool returns executions/fills from the current session/day. The verb 'get' and resource 'executions' are specific, and the scope 'current session/day' distinguishes it from potentially broader siblings like get_trade_history.
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?
Description implies it is for current session/day data only, but does not explicitly state when to use over siblings like get_trade_history or get_open_orders. No exclusion criteria or alternatives mentioned, 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.
Historical OHLCV bars.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Ticker symbol or numeric conId | |
| bar_size | No | e.g. '1 day', '1 hour', '5 mins' | 1 day |
| currency | No | USD | |
| duration | No | IB duration string, e.g. '5 D', '1 M', '1 Y' | 1 M |
| exchange | No | SMART | |
| max_bars | No | ||
| sec_type | No | STK | |
| what_to_show | No | TRADES, MIDPOINT, BID, ASK | TRADES |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only mentions 'OHLCV bars' but does not disclose data source, pagination, limits, or behavior for missing data. Minimal behavioral disclosure.
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?
Extremely concise (4 words) but sacrifices clarity and completeness. A single sentence without structure; important details are omitted.
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 8 parameters, no annotations, and the complexity of historical data retrieval, the description is wholly inadequate. It fails to explain how to use parameters, what OHLCV means, or any constraints. Output schema exists but does not compensate for lack of behavioral context.
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 50% (4 of 8 parameters have descriptions). The description adds no value beyond the schema; it does not explain parameters like bar_size, duration, or what_to_show. Does not compensate for low coverage.
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 'Historical OHLCV bars' indicates the resource (OHLCV bars) but lacks a clear action verb (e.g., retrieves, gets). It distinguishes from siblings like get_quote (current data) but is too terse to fully convey purpose.
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 siblings (e.g., get_quote for current data, get_trade_history for executions). No context about prerequisites or alternatives provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Date span and row counts of locally archived account history.
| 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 provided, the description carries the burden of behavioral disclosure. It indicates the tool is a read operation (returns data) and likely idempotent, but does not explicitly state it is safe or non-destructive. The simplicity of a parameterless tool mitigates risk, but more clarity on behavior would improve the score.
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 that front-loads the key outputs ('Date span and row counts'). It is concise with no unnecessary words, and every part 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 the tool has no parameters and an output schema exists, the description provides the essential information: what the tool returns. However, it does not clarify the scope (e.g., which account) or the meaning of 'locally archived,' which might be ambiguous. Still, for a simple metadata tool, it is fairly complete.
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?
The input schema has no parameters (0), so schema description coverage is 100%. The description adds no parameter information because none exist. Per calibration guidelines, a baseline of 4 is appropriate for zero-parameter tools.
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 tool returns 'Date span and row counts of locally archived account history.' It specifies the resource (locally archived account history) and the output (date span and row counts). While it distinguishes from siblings by focusing on metadata about the archive rather than live data, it does not explicitly differentiate from similar history tools like get_trade_history.
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 does not provide any guidance on when to use this tool versus alternatives. It lacks context such as prerequisites, typical scenarios, or suggestions to call this before fetching historical data to check coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open (working) orders across accounts.
| 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 are provided, and the description does not disclose behavioral traits such as read-only nature, scope limitations, or rate limits. It only states what it returns.
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, concise sentence that efficiently conveys the tool's purpose with no 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?
For a tool with no parameters and an existing output schema, the description is adequate. It provides the essential scope ('across accounts'), though it does not elaborate on the output format.
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?
There are zero parameters, so baseline score is 4. The description does not add parameter meaning beyond the empty schema.
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 tool retrieves open orders across accounts, using a specific verb and resource. It distinguishes from siblings like 'get_trade_history' which is for historical orders.
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 no guidance on when to use this tool versus alternatives like 'get_trade_history' or 'get_positions'. There is no mention of context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Today's realized/unrealized/daily PnL for an account.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Account ID; empty for the first managed account |
| 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 disclose behavioral traits. It only states the output is 'today's...PnL' but does not mention read-only nature, performance, or limitations. Minimal transparency.
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 sentence conveys the core purpose. No wasted words, front-loaded with key information.
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?
The tool is simple with one optional parameter and an output schema. The description is minimal but sufficient for an agent to understand the return of daily PnL. The output schema likely fills in return structure details.
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% with parameter description for 'account'. The tool description adds no additional semantics beyond the schema, meeting the baseline for high coverage.
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 tool retrieves today's realized, unrealized, and daily PnL for an account. The verb 'get' and resource 'PnL' are explicit, though it doesn't differentiate from siblings like get_portfolio or get_account_summary.
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 vs alternatives (e.g., get_portfolio for total value). No context on prerequisites or scenarios requiring PnL instead of other summaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Portfolio with market value, unrealized and realized PnL per position.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Account ID; empty for default account |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It indicates return data but no side effects, prerequisites, or safety behavior. Minimal but not misleading.
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 sentence, front-loaded with key information, 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?
Given simple input schema and presence of output schema, description covers the main output. Lacks usage guidelines but adequate for the tool's simplicity.
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% for the single parameter. Description adds no additional meaning beyond the schema.
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 returns portfolio with market value, unrealized and realized PnL per position. However, it does not differentiate from sibling tools like get_positions or get_pnl.
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. Context signals show many sibling tools but no comparative information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current positions with quantity and average cost.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Account ID; empty for all accounts |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry burden. It implies a read operation without destructive side effects, which is adequate for a simple query. However, no additional behavioral details (e.g., rate limits, data freshness, authentication requirements) are given.
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?
Extremely concise single sentence: 'Current positions with quantity and average cost.' Front-loaded with essential information, no extraneous 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, the description need not explain return values. However, with many siblings, the description lacks context on how this tool fits into the broader set. It is complete in its narrow scope but does not address possible confusion with similar tools.
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 has 100% description coverage for the single optional parameter. The tool description does not add any further insight beyond the schema's definition of 'Account ID; empty for all accounts.' 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 it returns current positions with quantity and average cost. However, it does not distinguish itself from sibling tools like review_positions or get_portfolio, which may overlap in purpose.
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. Context signals show many related tools (e.g., get_portfolio, review_positions) but description does not help agent choose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Market data snapshot (delayed by default; see IBKR_MARKET_DATA_TYPE).
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Ticker symbol or numeric conId | |
| currency | No | USD | |
| exchange | No | SMART | |
| sec_type | No | STK, CASH (forex pair like EURUSD), FUT, IND, OPT | STK |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It mentions delayed data by default, which is a key behavior, but omits other important aspects like error handling, required permissions, rate limits, or the impact of the IBKR_MARKET_DATA_TYPE setting.
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 at one sentence, but it sacrifices informativeness. Every word earns its place, yet the sentence is too sparse to fully guide the agent.
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, return values need not be described. However, the description fails to specify important usage context, such as typical use cases or boundary conditions (e.g., unsupported sec_types). It is insufficient for a tool with 4 parameters and many siblings.
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?
The description does not elaborate on any parameters. Schema coverage is 50% (only symbol and sec_type have descriptions), so the description should compensate by clarifying currency, exchange, or sec_type usage, but it does not.
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 'Market data snapshot' clearly indicates the tool retrieves current market data. It is specific enough to distinguish from historical data tools like get_historical_data, but could be more precise about the exact fields returned (e.g., bid, ask, last price).
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 no guidance on when to use this tool versus alternatives such as get_historical_data or get_pnl. The note about delay hints at configuration but does not explain decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Historical executed trades from the configured Flex query (up to its period, plus everything previously archived locally). Needs IBKR_FLEX_QUERY_ID + token; see README.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Only last N days; 0 = all | |
| symbol | No | Filter by symbol; empty for all | |
| max_rows | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description reveals that data is limited to the Flex query period plus local archive, and that it requires token and query ID. This adds useful behavioral context beyond a simple read operation, though it does not detail error handling or rate limits.
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 two sentences, each serving a distinct purpose: stating the data source and scope, then the prerequisites. It is front-loaded with the core functionality and avoids unnecessary detail.
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, the description sufficiently covers the tool's purpose, data sources, limitations, and prerequisites. However, it refers to an external README for configuration, which slightly reduces self-containment. Missing error scenarios are not critical due to output schema.
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 67%, with descriptions for 'days' and 'symbol'. The tool description adds prerequisite context but does not elaborate on the 'max_rows' parameter, which lacks a schema description. Overall, it adds some value but does not fully compensate for the missing schema description.
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 tool retrieves historical executed trades, specifies the sources (Flex query and local archive), and differentiates it from siblings like 'get_executions' and 'get_historical_data' by mentioning the Flex query dependency. The verb 'get' and resource 'trade history' are explicit.
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 is for trades from a configured Flex query but does not explicitly state when to use this tool versus alternatives like 'get_executions' or 'get_historical_data'. The prerequisite 'Needs IBKR_FLEX_QUERY_ID + token' is mentioned, but no direct guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List account IDs managed by the current TWS/Gateway login.
| 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 provided, the description carries full burden for behavioral disclosure. It only states that the tool lists IDs, but does not mention any behavioral traits such as read-only nature, permission requirements, error handling, or data freshness. This is minimal transparency.
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 that is concise, front-loaded, and contains no unnecessary words. It efficiently communicates the tool's 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?
For a simple tool with no parameters and an existing output schema, the description is largely adequate. It clearly states what the tool does and its scope. However, it could be slightly improved by noting that it returns only IDs and not additional details, but this is not a major gap given the context.
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?
There are no parameters, and schema description coverage is 100% (trivially). The description does not add meaning beyond the schema, which is acceptable. 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?
The description explicitly states the tool lists account IDs and specifies the scope ('managed by the current TWS/Gateway login'). The verb 'List' and resource 'account IDs' are clear, and it distinguishes from sibling tools that provide more detailed account information.
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 like get_account_summary or other account-related tools. The description does not mention prerequisites, exclusions, or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a symbol to a fully qualified IB contract (conId, exchange, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Ticker symbol or numeric conId | |
| currency | No | USD | |
| exchange | No | SMART | |
| sec_type | No | STK |
| 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. It only states that the tool resolves a symbol to a fully qualified contract, but does not disclose error behavior, required permissions, rate limits, or idempotency. The behavioral insight is minimal.
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 fluff, but it is too brief given that there are four parameters and an output schema. It earns its place but lacks detail, so it's adequate but not excellent.
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?
The tool has an output schema, so return values are documented elsewhere. However, the description omits context like what 'fully qualified' means and how conId input works. With low schema coverage, the description could be more complete, but it meets a minimal threshold.
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 only 25% (only symbol has a description). The description adds no additional meaning for currency, exchange, or sec_type parameters beyond what the schema provides with defaults. It fails to compensate for the low coverage.
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 'Resolve' and resource 'symbol to fully qualified IB contract', indicating a clear lookup operation. It distinguishes from siblings like get_quote and get_positions, but does not explicitly differentiate from search_contracts which may have similar functionality.
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, nor any when-not-to-use or prerequisites. The description only states what it does without contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Review open positions for loss discipline. Flags positions that have fallen past a loss threshold so a deliberate decision gets made — "has the thesis changed, or just the price?" — instead of defaulting to holding. Surfaces the book so the well-documented tendency to hold losers and sell winners (the disposition effect) gets a conscious check. Informational, not advice.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Account ID; empty for default account | |
| loss_threshold_pct | No | Flag open positions at or below this % return from cost, e.g. -15 |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses that the tool flags positions and provides consciousness checks, declares it informational (not advice), but does not explicitly state whether it is read-only, modifies data, or requires specific permissions. This leaves some behavioral ambiguity.
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 coherent but includes extraneous philosophical references ('disposition effect,' 'thesis changed?') that, while insightful, add length without necessary operational detail. It could be tightened to front-load the essential function.
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 low complexity (2 parameters, no required params) and existence of an output schema, the description covers purpose, behavioral nudges, and boundaries. It could be more complete by noting that flagged positions are returned, but the output schema handles that. Overall good context.
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% with descriptions for both parameters. The tool description does not add new semantic detail beyond the schema; it focuses on overall purpose. 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?
The description specifies the tool's purpose: reviewing open positions for loss discipline by flagging those past a loss threshold. It distinguishes itself from the sibling tool 'get_positions' by adding the loss discipline check and behavioral context, making its unique value clear.
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 use for loss discipline review but does not explicitly state when to use vs. alternatives or when not to use it. It lacks directives like 'use this when you want to identify positions needing deliberate decisions' and does not mention when to prefer other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search instruments by symbol or company name.
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | Yes | Partial symbol or company name |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose behavioral traits such as read-only nature, permissions, pagination, or result limits. The output schema exists but is not referenced.
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 sentence, no filler. However, it could be slightly expanded to include more context without becoming verbose.
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?
Output schema exists, reducing need to describe return values. However, given the presence of similar sibling tools ('lookup_contract') and the lack of any additional context about search behavior (e.g., wildcard support, case sensitivity), the description is minimally complete.
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% for the single parameter 'pattern', and the description in schema already states 'Partial symbol or company name'. The tool description adds no further meaning or usage nuances beyond the schema.
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?
Clearly states verb 'Search' and resource 'instruments', with method 'by symbol or company name'. However, it does not differentiate from sibling 'lookup_contract' which likely serves a similar purpose.
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 vs alternatives like 'lookup_contract' or when not to use it. Agent must infer usage from the name alone.
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. Dates show when Glama detected each change.
v0.4.1get_account_summaryget_cash_transactionsget_executionsget_historical_dataget_history_coverageget_open_ordersget_pnlget_portfolioget_positionsget_quoteget_trade_historylist_accountslookup_contractreview_positionssearch_contractsScored across 15 tools
Each tool targets a specific IBKR functionality (account summary, transactions, executions, PnL, positions, etc.) with no overlapping purposes. Clear distinction between similar concepts like portfolio vs. positions or trade history vs. executions.
All tool names follow a verb_noun pattern using snake_case. Verbs vary (get, list, lookup, review, search) but each is appropriate for its action, and the overall convention is uniform and predictable.
15 tools cover a broad range of IBKR account and trading operations without being excessive. Each tool serves a distinct purpose and the number is well-scoped for the domain.
The tool set provides excellent read capabilities but lacks any tool for placing, modifying, or canceling orders, which is a critical gap for a trading platform. Agents can analyze but cannot execute trades, making the surface incomplete for full lifecycle management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for OpenMM — exposes market data, account, trading, and strategy tools to AI agents
Open-source MCP server for Zerodha Kite Connect. Portfolio, market data, backtesting, alerts.
Multi-tenant FastMCP server for Charles Schwab brokerage data, monetized via DPYC Tollbooth
Hosted MCP for stocks, options, Greeks, brokers, order previews, alerts, and workflows.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jgalea/ibkr-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
