tastytrade-mcp

An MCP server that lets an autonomous AI agent (Claude, etc.) connect to Tastytrade — scan markets, build option strategies, inspect accounts/positions/orders, and (optionally) place and manage trades.

• OAuth2 authentication via the official tastytrade Python SDK (session tokens auto-refresh; refresh tokens are long-lived).

• Credentials stored in the OS keyring (Windows Credential Manager / DPAPI, macOS Keychain, Linux Secret Service) — never in files, never in env vars, never logged.

• Live trading is gated behind ENABLE_LIVE_TRADING — disabled by default so an agent cannot place real orders without an explicit opt-in.

• stdio transport by default; optional HTTP transport hardened with CORS and per-IP rate limiting.

Install

pip install -e .          # or: pip install -e .[dev] for tests

Related MCP server: FinClaw

1. Create a Tastytrade OAuth application

1. In the Tastytrade web app, open Manage → My Profile → API → OAuth Applications.

2. Create an application, select the scopes you need (read + trading), and add http://localhost:8000 as a valid redirect/callback URI.

3. Save the client secret (shown once).

4. Create a grant to obtain a long-lived refresh token.

Never paste secrets into code, .env, or version control.

2. Store credentials in the keyring

tastytrade-mcp secrets set
tastytrade-mcp secrets status

You'll be prompted (hidden input) for the client secret, refresh token, and an optional default account number. secrets status also shows which keyring backend is active — useful for diagnosing credential issues on a new machine.

Headless Linux (servers, Docker, CI)

Desktop Linux uses GNOME Keyring or KWallet. On headless systems (no desktop daemon) the native backend is unavailable. Install the encrypted-file fallback:

pip install 'tastytrade-mcp[headless]'
export PYTHON_KEYRING_BACKEND=keyrings.alt.file.EncryptedKeyring
tastytrade-mcp secrets set

EncryptedKeyring stores secrets in ~/.local/share/python_keyring/cryptedpass.cfg encrypted with a master password you set on first use. Keep this file out of version control. PYTHON_KEYRING_BACKEND selects the backend only; it is not a secret.

3. Configure

Copy .env.example to .env and adjust. Key flags:

4. Run

tastytrade-mcp                    # stdio (default)
tastytrade-mcp --transport http   # HTTP, CORS + rate limited

Connect an agent (stdio)

Claude Desktop / Claude Code MCP config:

{
  "mcpServers": {
    "tastytrade": {
      "command": "tastytrade-mcp"
    }
  }
}

Tools

Always available (read-only): get_connection_status, get_market_overview, get_option_chain, get_strategies, get_account_info, get_positions, list_accounts, get_working_orders, get_watchlists.

Only when ENABLE_LIVE_TRADING=true: execute_trade, adjust_order, close_position, manage_watchlist. Order tools default to dry_run=true (validate without submitting).

Underlying last price

get_market_overview now includes a last field (most recent trade price from DXLink) alongside the IV metrics for each symbol. Pass it directly as around_price in get_strategies and get_option_chain:

get_market_overview({ "symbols": ["XSP"] })
// -> { "ok": true, "metrics": [{ "symbol": "XSP", "last": 736.55,
//      "implied_volatility_index_rank": "0.48", ... }] }

last is streamed in parallel with the metrics fetch (best-effort, 4 s timeout). It is omitted per symbol when the DXLink feed is unavailable — fall back to the ATM strike from get_option_chain in that case.

Futures options

Both get_option_chain and get_strategies work with futures-options underlyings. Pass the futures root symbol prefixed with /:

get_option_chain({ "symbol": "/ES", "expiration": "2026-06-27",
                   "include_greeks": true, "around_price": 5650.0 })

get_strategies({ "symbol": "/ES", "target_dte": 0, "short_delta": 0.10,
                 "wing_width": 25, "around_price": 5650.0 })

The response shape is identical to equity options. instrument_type on each leg will be "Future Option" instead of "Equity Option" — use the correct value when constructing order legs for execute_trade. contract_multiplier in the get_strategies response reflects the option-to-futures ratio (typically 1.0); the dollar value per point depends on the underlying futures contract's own multiplier (e.g. $50/point for /ES, $5/point for /MES) — verify before sizing.

Delta-based iron condor construction

get_strategies builds a complete iron condor candidate with live credit and POP estimates. Pass around_price (the underlying's last price from get_market_overview) so strike selection uses live greeks from the DXLink feed — without it, the tool cannot center its greeks window and falls back to a positional heuristic that will pick the wrong strikes on large chains (e.g. XSP, SPX):

get_strategies({
  "symbol": "XSP",
  "target_dte": 0,
  "short_delta": 0.15,
  "wing_width": 5,
  "around_price": 738.50    // always pass — required for delta-accurate strikes
})
// -> {
//   "ok": true,
//   "strategy": "iron_condor",
//   "net_credit": 1.20,
//   "net_credit_per_contract": 120.0,
//   "estimated_pop": 0.70,
//   "quotes_complete": true,
//   "greeks_used_for_strike_selection": true,   // false = fell back to heuristic
//   "legs": {
//     "short_put":  { "strike_price": "736", "symbol": "XSP...P736", ... },
//     "long_put":   { "strike_price": "731", "symbol": "XSP...P731", ... },
//     "short_call": { "strike_price": "739", "symbol": "XSP...C739", ... },
//     "long_call":  { "strike_price": "744", "symbol": "XSP...C744", ... }
//   }
// }

greeks_used_for_strike_selection — check this field before acting on the result. When false, the greeks feed was unavailable and the tool fell back to picking the lower/upper third of the full strike list, which is rarely the right delta on a large chain. Cross-check the returned strikes against get_option_chain deltas before entry.

quotes_complete — when false, net_credit is null (the DXLink quote feed was temporarily unavailable). Do not estimate credit from strike prices; retry next iteration.

Per-strike greeks on the option chain

get_option_chain returns instrument fields per strike by default. Pass include_greeks=true to merge live delta, gamma, theta, and iv (annualized implied volatility) into each strike — useful for verifying strike placement, detecting put/call skew from per-strike IV, and assessing 0DTE gamma risk:

get_option_chain({
  "symbol": "XSP",
  "expiration": "2026-06-20",   // recommended with greeks (bounds the fetch)
  "include_greeks": true,
  "strike_count": 15,           // ATM window: 15 strikes each side (default); null = full chain
  "around_price": 581.40,       // center on the underlying's last price
  "greeks_timeout": 6.0
})
// -> chain[expiration] = [
//   { "strike_price": "580", "option_type": "Put", "symbol": "...",
//     "streamer_symbol": ".XSP...", "delta": -0.18, "gamma": 0.042,
//     "theta": -0.95, "iv": 0.187 }, ... ]

Greeks come from the DXLink streaming feed (not the chain endpoint), so this adds latency and is opt-in. With include_greeks and no expiration, the tool defaults to the nearest expiration to bound the subscription. An ATM window is applied by default (strike_count defaults to 15 strikes each side of the money, centered on around_price or the median strike) to keep the subscription small and fast; pass strike_count: null for the full chain. If the feed is slow or unavailable, the chain is still returned and greeks_complete / greeks_received report coverage rather than failing.

Order safety layers

A live order requires all of the following, so it cannot happen by accident:

1. ENABLE_LIVE_TRADING=true — otherwise the order tools are not registered at all.

2. FORCE_DRY_RUN=false — when set to true, every order is forced to dry-run regardless of what the agent requests ("propose-only" mode).

3. The agent explicitly passes dry_run=false on the call.

Before any submission, execute_trade / adjust_order run a pre-flight dry-run and validate buying power: the order is rejected if it would leave projected buying power below the required reserve (BUYING_POWER_BUFFER_PCT of current buying power; with the default 0 it only blocks orders that would go negative), or if the API returns errors. Rejections return {"ok": false, "error": "pre-flight validation failed", "problems": [...]} and nothing is submitted. The projected buying-power effect — including required_reserve and buffer_pct when a buffer is set — is returned on every call under "buying_power".

Account-wide deployment cap. ACCOUNT_DEPLOY_LIMIT_PCT adds a ceiling on total deployed buying power (vs. the per-order BUYING_POWER_BUFFER_PCT). It is derived from live account state — used_derivative_buying_power vs. derivative_buying_power — not an in-memory counter. Capacity = used + available; the limit is that percent of capacity, and an order is rejected if it would push deployed buying power past it. Because it reads the account each time, it counts buying power consumed by existing positions (even ones this server didn't place) and stays correct across restarts and multiple server instances. The figures (account_deployed_current, account_deployed_after, account_deploy_limit, account_buying_power_capacity) appear in the "buying_power" block.

Safety

• Account numbers are masked in logs to the last 4 digits (****1234); secrets are never logged.

• HTTP transport restricts CORS to a single configured origin and rate-limits to 120 requests/minute per IP (HTTP 429 when exceeded).

Development

pip install -e .[dev]
pytest                       # unit + integration tests (SDK mocked, no network)
pytest --cov                 # with coverage report

Live integration tests

A separate, opt-in suite hits the real Tastytrade API using your stored credentials to confirm the SDK + OAuth + API contract works end-to-end. It is skipped by default and never submits a real order (the test server runs with force_dry_run=true). To run it:

tastytrade-mcp secrets set     # if not already stored
RUN_LIVE=1 pytest -m live -v

Tests that depend on endpoints which are intermittently unavailable (e.g. /market-metrics) skip themselves on a 5xx rather than failing.

Disclaimer

This software can place real orders against a live brokerage account. It is provided "as is", with no warranty, and is not financial advice. You are solely responsible for any trades it places and any resulting losses. Review the order-safety controls above before enabling live trading. The built-in risk checks reduce — but do not eliminate — the risk of an unintended or oversized order.

This is an independent project and is not affiliated with, endorsed by, or sponsored by tastytrade. It uses the unofficial third-party tastytrade SDK.

License

MIT © 2026 Jon Covington