ibkr-risk-mcp

MCP server exposing Interactive Brokers' portfolio risk: IB's model greeks, IB's implied volatility surface, IB's what-if margin, and a local stress engine that rebuilds the P&L-versus-underlying curve and finds its trough.

It deliberately does not duplicate the official IBKR connector. Positions, balances, orders, trades, performance, allocation, spot and historical prices, option chains, watchlists and alerts all come from there. This server exists to fill the one gap that connector leaves — risk analysis — and nothing else.

The questions it is built to answer:

• where is the trough of the portfolio's P&L curve across underlying shocks, at constant volatility?

• and how much of that answer is the constant-volatility assumption itself?

• if I add N puts at strike K expiring E, where does that trough move to?

• how much margin does this hypothetical structure need, now and under stress?

• what does IB's volatility surface look like for this underlying?

Risk Navigator's risk model is not exposed by any API, so the strategy is to pull the inputs from IB — per-contract implied volatility, model greeks, what-if margin — and rebuild the curves locally, rather than trying to read Risk Navigator itself.

Prerequisites

1. TWS or IB Gateway running and logged in. The server talks to its socket directly; it never reaches IBKR over the internet. Usually that is the same machine — for a Gateway on a host the server reaches over the network instead, see docs/remote.md.

2. The API enabled. File → Global Configuration → API → Settings → tick Enable ActiveX and Socket Clients. Until you do, TWS opens no port at all and check_connection reports not_listening.

3. Market data for the instruments you hold. Model greeks come from IB's own option model, so a contract the account cannot price has no greeks and is reported under missing. Contrary to what is widely repeated, delayed data does carry model greeks — verified against live TWS, where an unsubscribed account got nothing from market data types 1 and 2 and implied volatilities from type 3. If you lack the subscription, set IBKR_MARKET_DATA_TYPE=3 and read the numbers as a quarter of an hour old.

4. For whatif_order only: Read-Only API must be off in that same TWS screen. That setting blocks what-if orders too.

Default ports: 7496 TWS live, 7497 TWS paper, 4001 Gateway live, 4002 Gateway paper. If the configured one is dead, check_connection scans all four and tells you which is answering.

Install

{
  "mcpServers": {
    "ibkr-risk": {
      "command": "uvx",
      "args": [
        "--from",
        "https://github.com/simoneb/ibkr-risk-mcp/archive/refs/tags/<TAG>.tar.gz",
        "ibkr-risk-mcp"
      ],
      "env": {
        "IBKR_PORT": "7496",
        "IBKR_CLIENT_ID": "17",
        "IBKR_ENABLE_WHATIF": "false"
      }
    }
  }
}

Pin a tag rather than a branch, and prefer the archive URL over git+https://… — the git form needs git on PATH, and some clients hand the server too small an environment to find one.

For a local checkout:

uv venv && uv pip install -e ".[dev]"
uv run python -m ibkr_risk_mcp.server

As a Claude Desktop extension, manifest.json surfaces host, port, client id, account, market data type, risk-free rate and the what-if gate as a settings form, so none of them need editing by hand.

Over HTTP

The default transport is stdio — a server the client launches as a subprocess — and everything above assumes it. IBKR_MCP_TRANSPORT=http serves streamable HTTP instead, for a server running somewhere the client cannot launch it: beside an IB Gateway on a host that stays up, behind a reverse proxy, reached as a custom connector.

That mode adds a bearer-token boundary (OAuth 2.1 resource server, tokens issued by an identity provider you choose), a service unit, and a set of timeouts measured rather than guessed. All of it is in docs/remote.md; none of it changes the stdio path, which remains the default and is unaffected.

Environment variables

Copy .env.example to .env for local runs.

The HTTP transport and its authentication add IBKR_MCP_* variables — transport, listen address, path, and the bearer-token settings. They are documented in .env.example and in docs/remote.md; none of them affect a stdio run.

Tools

Each tool carries the protocol's annotations, so a client can group them by permission. Seven are marked read-only. whatif_order is not, because it puts something on IB's order channel even though nothing is routable; calibrate_vol_coord is not either, because it writes the fit to disk — neither of them changes anything in the account.

Reading the curve: by symbol, by expiry, at another date

Every stress result carries the P&L broken down per shock. By default that breakdown is keyed on the symbol, which is the right unit for a book of many underlyings and the wrong one for a book running one underlying across many expiries: nine ES expiries all land under a single ES key, and the operative question — which expiry is holding the trough down, and which short do I buy back — has to be reconstructed by hand from the position list.

breakdown changes the key. expiry groups on the option's settlement date (ES 2026-10-30), so a quarterly and a weekly that settle the same morning are one row rather than two names for one expiry. Positions with no expiry get a key naming their class — ES (future), AAPL (equity) — so the breakdown still sums to the point's total and can be checked against it rather than trusted. both returns symbol and expiry, none neither, and symbol remains the default: the responses are already large, and a second dictionary at every one of twenty-six shocks is not free.

With an expiry breakdown the result also carries troughByExpiry, two columns per expiry that answer two different questions:

• pnl — that expiry's own worst point along the curve, which is what it can cost.

• pnlAtPortfolioTrough — what it contributes at the shock where the account's floor actually sits, which is what says whether closing it would move that floor.

They come apart, and the gap is the useful part. An expiry whose own minimum sits at −35% while the book troughs at −22% is not the one to buy back, and reading only the first column would nominate it.

Valuation dates. date_offset_days rolls the clock forward; valuation_date takes the ISO date instead, so "the curve at 30 September" does not have to be counted out by hand over a weekend. There is no calendar adjustment — the date is the date — and both forms mean the same thing: the P&L is still measured from today, at today's spot and today's implied volatilities, with time advanced. That is decay and the change in convexity that comes with it, not a forecast of where the market will be.

stress_curve takes a family of them, date_offsets: [0, 3] or valuation_dates: [...], and crosses them with the volatility scenarios. That is not a convenience: comparing today against Monday used to take two calls, and the book and the market moved between them, so part of the difference between the two curves was not the three days at all. One call, one loading of positions and prices, and time is the only thing that changed. Each entry under curves carries its own valuationDate and dateOffsetDays; name stays the scenario's and label distinguishes the pair.

The what-if gate

whatif_order works only with IBKR_ENABLE_WHATIF=true. Otherwise it sends nothing and returns success: false with blocked: true.

An order carrying whatIf=True is evaluated by IB's margin engine and discarded — never routed, never acknowledged as live, never in the order book. The gate exists anyway, for two reasons. It is the only thing in this server that touches the order path at all, so being read-only should be provable rather than asserted; and with the gate closed the ib_async connection itself is opened in read-only mode, which makes an order impossible below this server as well as inside it.

No tool here can submit a live order. Those belong somewhere else.

The traps this server handles

These are not hypothetical; each one produces a confidently wrong number if you skip it.

Expiry dates are reported twice, and AM settlement does not always move the date. For AM-settled contracts — the quarterly ES options, trading class ES — some TWS builds report lastTradeDateOrContractMonth as the day before settlement, so an 18 December expiry shows as the 17th while a PM weekly expiring the same morning shows as the 18th; time to expiry taken from the last trading day is then a day short.

But that is not universal, and assuming it is would introduce the error it was meant to prevent. Measured on TWS server 178: the December ES quarterly reports 20261218 — the correct date — with the AM settlement visible only in lastTradeTime='08:30:00' against the weekly's 15:00:00. IB's own ContractDetails.realExpirationDate exists for exactly this ambiguity and is preferred wherever the details have been fetched; the class-and-date heuristic is only the fallback. Every tool returns both lastTradeDate and settlementDate plus an amSettled flag, and everything downstream uses settlement.

The underlying is not implied by the expiry — and two options expiring the same morning need not share one. Confirmed against live TWS: the 18 December 2026 ES quarterly is written on ESZ6, while the EW3 weekly expiring that same day is written on ESH7. The 30 September end-of-month options are on ESZ6, not ESU6. underConId comes from the contract details and is never inferred from a date.

Portfolio contracts arrive unqualified. The contracts on IB's PortfolioItem come back with exchange empty, and reqMktData on a contract without an exchange returns nothing at all — no ticks, no error. This is why a live book returned no model greeks at all for any option position while a surface request on the same underlying worked perfectly: those contracts had come from reqContractDetails already qualified. Every position is requalified before its data is requested.

impliedVol and undPrice arrive in separate ticks. Taking the greeks the moment a volatility appears leaves the underlying unset a good fraction of the time — a sizeable minority of positions on a measured live run — and without a forward there is nothing to reprice against, so the position silently drops out of the curve. Both fields are waited for, and a missing forward is backfilled from another position on the same underlying before it is fetched again.

A refusal is an answer; don't wait it out. IB replies to a market data request in about a second or not at all, and when it is "not at all" it usually says so at once with error 354 or 10091. Those are watched for and end the wait immediately. Without that, an unentitled book pays the full timeout on every contract — the difference between a check taking 30 seconds and taking minutes.

Where IB won't publish greeks, the price is already in the portfolio. Error 10091 — "requires additional subscription for API" — refuses the option's greeks and a quote on its underlying, so the obvious fallback of implying a volatility locally dies for want of a spot price. But a book holding GOOGL stock next to a GOOGL option already knows what GOOGL is worth: every position carries its own mark on the portfolio update, which arrives over the account channel and is gated by no market data entitlement at all. Underlying prices are taken from the account's own positions before a market data line is ever spent. Measured on a live account, this is the difference between two long puts priced and the same two held flat across every shock — worth 2,826 at a 15% fall and 4,414 at 20%, on a 138k account. A long option contributes a multiple of its premium under shock, so judging it by its market value understates it badly.

reqCalcImpliedVolatility can take the connection down, so it is opt-in. Asking IB to run its own American-exercise model on prices you supply is the better answer than implying a European volatility locally — when it works. Measured against live TWS: ib_async's request is answered with error 320, "Error reading request. Please use 'Key=Value' format for Misc Options", and TWS then closes the API connection. A protocol error halfway through a portfolio load costs the whole load, which is far worse than the one contract it was trying to rescue. It is behind IBKR_USE_IB_IMPLIED_VOL, off by default, and disables itself for the rest of the process after a single failure. The local implication is stamped with its source and never passed off as IB's own either way.

A bare root is ambiguous. ES is the E-mini S&P 500 future and Eversource Energy on NYSE. With no sec_type the stock wins, and you get a plausible-looking volatility surface with 75-dollar strikes. Every resolution reports what else the symbol matched, and get_vol_surface returns the contract it actually used.

IB requires transmit=True on a what-if order. With transmit=False — the intuitive choice for something meant not to trade — TWS rejects it with error 321 and, because it rejects rather than answers, the call never returns at all. whatIf=True is what keeps the order off the market; transmit has nothing to do with it. Every what-if here is also bounded by a timeout, because IB not answering is an ordinary outcome.

The volatility level does not move with the shock unless you make it. Both vol modes decide which volatility a strike gets, not how high the surface sits: sticky_strike pins each strike to the volatility it holds today, sticky_moneyness slides a strike along the smile the portfolio already has. Neither raises the level, and vol_bump cannot either — it is flat along the shock axis by construction. So the default curve prices the move in the underlying and none of the move in volatility that comes with it, which for a net short option book is the optimistic half of the answer and can be the larger half. vol_slope_down puts it in: 1.0 adds one volatility point per 1% fall, so a −20% shock reprices at +20 points. It is applied as a parallel shift across every tenor — a real surface also steepens in a sell-off, and a 120-day volatility moves less than the front month — so it is an input to be chosen and stated, in the same class as bond_duration_years. Expect it to change the shape of the curve and not only its depth: on the measured fixture it deepens the −10% and −20% points while lifting the −30% tail, because the long wings pick up vega faster than the short body does.

Volatility has a term structure. ES at 139 days can sit near 15% at the money while the front month prints 12%. Using one ATM number for every tenor understates a long-dated position badly. The surface interpolates per tenor, in total variance rather than in volatility, which is also what keeps it free of calendar arbitrage.

Bonds are quoted as a percentage of nominal. 50,000 nominal at 97.85 is worth 48,925, not 4,892,500 — quantity × price is wrong by 100×. Position values come from IB's own marketValue, and the reconciliation below is what proves it worked.

Futures have no market value to add. Variation margin settles daily, so a future contributes its unrealised P&L to NetLiquidation, not its notional. Adding the notional instead moves the total by a quarter of a typical account.

Two accounts must never be added together. ib.portfolio("") and ib.accountValues("") do not mean "the default account", they mean all of them. On a multi-account login with no IBKR_ACCOUNT set, that would combine two portfolios and reconcile the total against one account's NetLiquidation — a wrong answer wearing the shape of a right one. Every tool that reads positions or account values refuses until an account is chosen, and names the candidates. Related: IB permits only one reqAccountUpdates subscription at a time, so asking about a second account silently cancels the first; only the resolved account is ever subscribed.

Reconciliation. stress_portfolio rebuilds the portfolio at zero shock — cash, plus the securities' market value, plus the futures' unrealised P&L — and compares it against NetLiquidation. A residual over 1% returns reconciled: false with the residual attached. Nothing derived from a portfolio that does not reconcile should be presented as fact.

A minimum at the edge of the range is not a trough. If the curve is still falling at −30% the engine says so, rather than reporting the boundary as the worst case. Some portfolios simply keep losing past the edge of the window.

Known limitations

Risk Navigator's volatility shock model is not public. It is not exposed by any API and IB does not document it. sticky_strike — each strike keeps its current implied volatility — is the approximation corresponding to Risk Navigator's default blue curve. Expect the shape to match and the last few percent not to. Do not present a number from this server as "what Risk Navigator says"; it is what a documented model, fed IB's own volatilities, says.

One shock, all underlyings — and only the equity ones. Every underlying in scope is moved by the same percentage at once, which is Risk Navigator's own default assumption. There is no correlation matrix and no per-underlying scenario.

Because of that, scope defaults to equity: only equity underlyings are on the axis, and FX, rates and the rest are excluded outright and listed under excluded with their market value. This is not a refinement, it is what makes the number mean anything — one percentage applied to every underlying at once is nonsense off the equity axis, where a 20% shock on a currency future prices an exchange rate that has never traded there. On a live account a single CAD strangle was contributing −21,716 at −20% and −7,183 at +10%, against −29,027 and +2,408 for an entire ES campaign: it dominated both tails of a curve that was supposed to be about equities. TWS Risk Navigator draws the same line in its Equity tab, and once it is drawn here too the two curves agree to 34 dollars on 29,000 at a 15% fall. scope='all' restores the old behaviour.

The classification is a table plus one heuristic — a three-letter currency code on a FUT or FOP is IB's own naming for a currency future — not a deduction, because IB publishes no reliable asset class for futures and a bond or gold ETF quoted as STK lands in equity with no field to say otherwise. So the group is reported on every position and risk_groups overrides it per symbol.

betas scales that shock per symbol, and it reaches every class that responds to one — an option is repriced at its own beta-scaled move of its underlying, with strike, smile and convexity all measured at the forward it would actually reach, rather than having its P&L scaled after the fact. Keys are tried most specific first: local symbol (ESZ6 P5800), then root (ES), then underlying (ESZ6).

This is what lets a foreign underlying be stood down off an equity axis — a short EUR strangle is not a 20%-down position when the S&P falls 20%, and a single shock across every underlying says it is. But read what a beta does and does not do. It scales the underlying's move only: vega and theta are untouched, so a position at beta 0 still contributes P&L the moment vol_bump or date_offset_days is set, and pnl_by_symbol is the only clean exclusion. More importantly, standing a position down is not measuring it — an attenuated strangle carries its whole gap risk and none of that risk is anywhere on the curve. Every run that applies a beta other than 1 says so in warnings.

Volatility surface interpolation is local. Under sticky_moneyness the surface is built from the strikes the portfolio actually holds — one skew per expiry that has at least three of them, assembled into a surface and interpolated across tenors in total variance. An expiry too thin to define its own slope borrows its shape from the tenors that do; an underlying where no expiry defines one falls back to sticky_strike rather than being handed an invented flat smile. Either way it is said in warnings. fetch_skew=true pulls neighbouring strikes from IB instead, at the cost of more market data requests.

The surface supplies the change in volatility as a strike slides to new moneyness, not the level. The level stays IB's own per-contract implied volatility, which comes out of a model that prices American exercise and is a better number than any fit through it. Reading the level off the surface would also break the curve's zero: a strike whose shape was borrowed from another tenor would not get its own volatility back at zero shock. Every result carries volSurfaceUsed, the quotes the repricing actually read — if it is empty under sticky_moneyness, no smile was built, every option silently fell back to sticky_strike, and the result is not the model you asked for.

The volatility response is IB's own model, and both curves are validated against Risk Navigator. Risk Navigator draws two lines: a constant-volatility curve, and one it labels Vol.Coord. where volatility moves as a deterministic function of the price shock. IB documents that second model's shape — the nominal shock is -X on a rise and -10X on a fall, applied relatively rather than in points, then damped across tenors by a response function VR(t) that is 1 at zero and decreasing. vol_coord implements it. Measured against a live index ratio book, on a −30% to 0% axis:

with the residual at every shock inside the error of reading the targets off a chart by eye. VR(t) itself is not published: vol_coord_decay is fitted here, exp(-4.736 t), on one book from nine points read off a chart by eye. Two things follow, and the engine says both out loud rather than leaving them in the docs.

Every vol_coord curve running on the shipped decay says so in warnings. And the fit was constrained only out to 0.345 years, because that is all the book it came from held; past there an exponential does not merely lose accuracy, it decays to nothing. At one year VR is 0.009, so this model would reprice a LEAPS as though a 20% crash barely touched its volatility. Any position beyond vol_coord_calibrated_to_years is priced anyway and named in warnings, because a silent extrapolation that understates long-dated vega is exactly the failure this server exists not to have. A floor on VR would tidy the symptom away and hide it, so there isn't one.

To replace the number rather than trust it, call calibrate_vol_coord with four or more readings off Risk Navigator's own Vol.Coord. curve on its Equity tab — {shock: -0.20, pnl: -28000}, shocks as fractions. The same fit is available from a shell:

uv run python scripts/calibrate_vol_coord.py -- -0.05=-8000 -0.10=-22000 -0.15=-31500 -0.20=-28000 -0.25=-12000

Either route refits the decay and returns the residual at every point, the tenor range your positions actually constrain, and the most extreme volatility the fit produces — a decay that reproduces the curve by pricing a wing at 150% has fitted the chart rather than the market, and it tells you so.

The fit is kept. It goes to ~/.ibkr-risk-mcp/vol_coord.json (IBKR_CALIBRATION_FILE moves it) and becomes the default vol_coord_decay for every later stress_curve on that machine, no restart and nothing to carry by hand — which was the actual reason the shipped number kept being the one in use. Stored beside it is what it was fitted against: the targets, the residuals, the account, the date. A calibrated run then reports that provenance in assumptions.volCoordDecaySource and in warnings instead of the "factory decay" caveat, and a decay you pass explicitly is described as neither — this server did not fit it and does not vouch for it.

A fit taken against a portfolio that does not reconcile is returned but never stored. The asymmetry is the point: a curve missing a position announces itself through reconciled, while a decay that absorbed the same gap would go on deforming every later run with nothing to give it away.

Being relative is the part that matters, and it is why the additive slopes were removed from the defaults. Multiplying every volatility by the same factor puts more points on a wing already quoted at 41% than on a 31% at-the-money, so the surface steepens by itself. A parallel shift in points cannot do that at any slope, and on a ratio book the difference is not a matter of degree: the additive model made the curve monotonically worse through the region where Risk Navigator turns it back up, and put its crossover around −35% where Risk Navigator puts it near −18%. Measured there, vol_coord troughs at roughly 60% of the depth of the constant-volatility curve and at a much shallower shock — so a rising-volatility regime came out as the better one, the opposite of what a naive short-vega reading predicts. That is the reason the regimes are returned as separate curves rather than as a band.

The additive slope alternative is your input, not a measurement. Neither vol mode moves it: sticky_strike pins volatility to the strike and sticky_moneyness slides a strike along today's smile, so with both slopes at zero the curve prices the move in the underlying and not the move in volatility that comes with it — the optimistic half of the answer for a net short option book. vol_slope_down puts it in, at volatility points per 1% fall. It is applied as a parallel shift, flat across tenors, and a real surface does neither: it steepens in a sell-off, which understates a long out-of-the-money put, and the front month moves more than a 120-day tenor. A steepening term was tried and removed — the values that reproduced the observed shape priced the long wings above 100% implied volatility, which is curve fitting rather than modelling.

stress_curve exists because of that. Rather than burying one regime in one result, it returns a curve per regime over a single loading of the portfolio and a single surface, so the curves differ by assumption alone — by default the same two Risk Navigator draws. Read the slope-0 curve first: it is the constant-volatility case and the only one with an external check against Risk Navigator's blue line — and it passes. Measured against a live index ratio book, stress_curve at vol_mode='sticky_strike', slope 0, tracks Risk Navigator's blue curve to within 1-3% at every shock from 0 to −30%. That check only works in sticky_strike, which is why it is the default here; sticky_moneyness is a different model and on the same book put the trough 1.8x deeper. And do not assume the steepest slope is the worst case everywhere — on a book holding long wings the ordering reverses in the far tail, where the least-deep long puts carry the most vega and a rising volatility starts helping.

The local repricing is European; most of these options are American. Black-76 has no early exercise, while equity options and CME futures options both do. The gap is negligible out of the money and real once an option is in the money. Measured against live IB data: a 75-strike put with spot at 71.94 priced at 4.51 locally against IB's 4.65, a 2.9% shortfall that is the early-exercise premium and nothing else. It is reported per position as modelVsMarket rather than hidden, and it means the curve slightly understates losses deep in the money.

Rates are an input, not a measurement. IB does not publish the rate behind its own model. IBKR_RISK_FREE_RATE moves option values by little over the horizons this server deals with, but it is not zero either, and it is part of the modelVsMarket residual above.

Currency. Everything is summed in the account's base currency as IB reports it. A portfolio with positions IB values in another currency will show up as a reconciliation residual rather than being converted.

No exchange holiday calendar. The AM-settlement shift moves to the next weekday. An expiry the day after a holiday would be off by one, and that shows in settlementDate rather than hiding.

Tests

uv run pytest -q                      # unit tests, no TWS needed
uv run python scripts/smoke_test.py   # end-to-end, needs TWS

The unit tests run the whole repricing layer against recorded JSON fixtures in tests/fixtures/, with the valuation date pinned, so a pricing bug is distinguishable from a market data problem and the numbers do not drift as time passes. The fixture portfolio holds an AM-settled quarterly and a PM-settled weekly on the same morning, a future, an equity and a bond — every trap above, in one file.

scripts/smoke_test.py exercises the live path: connection, greeks with a count of any missing modelGreeks, a surface, stress_portfolio from −30% to +30% in 1% steps with the reconciliation check, stress_curve over its three default regimes — checking both that the constant-volatility curve starts at zero and that volSurfaceUsed is not empty — stress_whatif, and a whatif_order on a single deeply out-of-the-money leg. Point .env at the paper port to try it safely.

Layout

src/ibkr_risk_mcp/
  server.py       MCP tool definitions — the docstrings are the interface
  connection.py   ib_async lifecycle, one connection, four failure modes
  marketdata.py   greeks, vol surface, rate limiting, portfolio snapshot
  pricing.py      Black-76 / Black-Scholes, skew and surface interpolation
  stress.py       the stress and what-if engine
  margin.py       whatif_order and the segmented margin summary
  contracts.py    expiry and underlying normalisation
  calibration.py  where the fitted vol_coord decay is stored between sessions
  auth.py         bearer token verification, for the HTTP transport only
scripts/smoke_test.py
scripts/calibrate_vol_coord.py
scripts/http_smoke.py       drives the HTTP transport as a real client would
docs/remote.md              running it over HTTP: auth, timeouts, the service unit
tests/

pricing.py and contracts.py have no IB dependency at all, which is what makes them testable.