ib-gateway-mcp

Historical bars

get_historical_bars

Read-only

Get historical OHLCV bars for any financial instrument, from intraday to monthly. Specify duration, bar size, and trading hours to retrieve the price history you need.

Instructions

Return historical OHLCV bars for one instrument, oldest first.

Bars cover `duration` back from `end` (now when omitted). Intraday bar times are UTC;
daily, weekly and monthly bars carry the trading date. Default limit 1000 bars, at
most 10000; when there are more, the NEWEST are kept and `truncated` is true (request
a shorter duration or larger bars to see older ones).

Limits (IBKR): bars of 30 seconds or less reach back about 6 months, allow short
durations only (1 secs up to 1800 S, 5 secs up to 3600 S, 10/15 secs up to 14400 S,
30 secs up to 28800 S), and are paced at about 60 requests per 10 minutes, 5 per
contract and data type in 2 seconds, and no identical request within 15 s (this
server answers identical requests from a 15-second cache). Larger bars are not paced
that way; IBKR's guide for the longest duration: 1 min bars about 1 D, 3 mins 1 W,
30 mins 1 M, daily bars years. Needs market-data permissions for the instrument (the
same subscription as live quotes). IBKR keeps no data for expired options; expired
futures need include_expired in the contract.

Errors: not_found (no such contract, or no data in the range: check
what_to_show, use_rth and get_head_timestamp), invalid_request (bad duration or
bar size combination), rate_limit (pacing; retry after the stated time),
ib_api_error 162 (pacing, permissions), request_timeout (shorten the request).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`end`	No	End of the range, ISO 8601 (no offset means UTC). Omit for now.
`limit`	No	Maximum number of items to return. Omit for the tool's default; larger values are capped. The result's truncated flag says whether more were available.
`use_rth`	No	True: regular trading hours only. False: include pre-market, after-hours and overnight data.
`bar_size`	No	Length of one bar, e.g. '5 secs', '1 min', '15 mins', '1 hour', '1 day'.	1 hour
`contract`	Yes	The instrument. A con_id alone is unambiguous; otherwise give symbol and sec_type, plus expiry, strike and right for options.
`duration`	No	How far back from end: '<n> S\|D\|W\|M\|Y', e.g. '1800 S', '5 D', '2 W', '6 M', '1 Y' (M means months). Words like '30 mins' also work.	1 D
`what_to_show`	No	Data the values are built from. TRADES (not for forex), MIDPOINT, BID, ASK, BID_ASK (counts double for pacing), ADJUSTED_LAST (split/dividend adjusted; end must be empty), HISTORICAL_VOLATILITY and OPTION_IMPLIED_VOLATILITY (stocks, indexes), REBATE_RATE and FEE_RATE (stock loan), YIELD_BID, YIELD_ASK, YIELD_BID_ASK, YIELD_LAST (bonds), AGGTRADES (crypto).	TRADES

Output Schema

TableJSON Schema

Name	Required	Description
`end`	No	Requested end (UTC); null means now.
`bars`	Yes	Oldest first; when truncated, the newest bars are the ones kept.
`total`	Yes	How many bars IBKR returned before the limit.
`use_rth`	Yes	True when only regular trading hours are included.
`bar_size`	Yes
`contract`	Yes
`duration`	Yes	The duration sent to IBKR, e.g. '5 D' or '1800 S'.
`truncated`	No	True when the result was cut to the limit.
`what_to_show`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 23, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true and openWorldHint=true, and the description is consistent with those. It adds substantial behavioral context beyond the annotations: truncation behavior (newest kept, truncated flag), UTC vs trading-date time semantics, IBKR pacing limits (60 requests/10 min, 5 per contract/data type in 2s, 15s cache), data availability limits for expired contracts, and permission requirements. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-organized: first sentence states the core purpose, then range semantics, then limits/truncation, then IBKR pacing, then errors. It is longer than average, but every sentence carries operational information an agent needs. The error list is compact and actionable. Slight redundancy in the pacing section (multiple rate limits listed) but all are distinct constraints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 7 parameters, an output schema, and complex IBKR-specific constraints, the description covers all the critical operational context: range semantics, truncation, pacing, permissions, expired contracts, and error handling. The output schema exists so return values need not be described. The only minor gap is that it doesn't explicitly state the output format, but the output schema covers that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 7 parameters. The description adds value by explaining the interaction between duration and bar_size (e.g., 'bars of 30 seconds or less reach back about 6 months'), the meaning of the truncated flag relative to limit, and the end default ('now when omitted'). It doesn't restate every parameter but adds cross-parameter context that the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Return historical OHLCV bars for one instrument, oldest first.' This clearly distinguishes it from siblings like get_historical_ticks (ticks vs bars) and get_head_timestamp (timestamp only). The scope is explicit: one instrument, OHLCV bars, chronological order.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides extensive usage guidance: it explains how duration/end define the range, when truncation occurs and how to avoid it, IBKR pacing limits and duration reach, market-data permission requirements, and the include_expired caveat for futures. It also lists specific error conditions and remediation steps (check what_to_show, use_rth, get_head_timestamp). This is far beyond a minimal when-to-use statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server