Skip to main content
Glama
Crypto Options Desk MCP

Crypto Options Desk MCP

by HarryWarre

Crypto Options Desk MCP

A Model Context Protocol (MCP) server that gives an LLM agent one typed, audited, read-only-by-default tool surface over a quant crypto-options desk's analytics: gamma exposure, vanna, skew, vol surface, options flow, technicals, portfolio greeks, scenario analysis, vol-selling signals, and live positions.

Point Claude (Desktop or Code) at it and ask "give me a BTC options market memo" — the agent calls the tools itself and reasons over real Bybit data.

What it actually does, end to end: the LLM drives the whole desk. It calls the flow tools (GEX, vanna, skew, vol surface) to read dealer positioning, the sentiment/funding/OI tools to read the crowd, the technicals for trend, and the IV-RV / vol-selling / strategy tools to find an edge — then it cross-checks those numbers against each other and writes a trader-grade memo: regime call, the structural shifts that matter, defined-risk trade ideas with strikes/breakevens, an allocation, and a risk checklist. With a read-only API key it also pulls your live book and folds current positions into the same analysis. The math is identical to what the (private) strategy bots run — the agent just narrates and reasons over it.

See the examples/ folder for real outputs: full market memos from both Claude and Codex (*_market_analysis_2026-06-07.md) and the delta updates they produced ~11h later (*_market_analysis_2026-06-08.md) — each diffs the new snapshot against the prior one (spot, IV, GEX, funding, OI) and tells you what changed and why it matters, not just where the market is.

Extracted from a private multi-strategy trading desk. This is the analytics surface only — no strategy signals, thresholds, or alpha. The server is a thin facade; all math lives in the bundled libraries (options_lib, indicators_lib, portfolio_lib, bybit_api) — the same code the (private) strategy bots import directly. One implementation, surfaced two ways.


Contents


Related MCP server: Crypto Options Desk MCP

Install

Requires Python ≥ 3.11.

# with uv (recommended)
uv venv && uv pip install -e .

# or plain pip
pip install -e .

This installs the trading-mcp console command (it speaks MCP over stdio).

Multi-asset scanner

The read-only web scanner is a separate research interface. It discovers active Bybit option assets, builds an observed/interpolated volatility surface, prices defined-risk long call/put candidates, and shows market-versus-model edge after configurable costs.

The read-only API also exposes GET /api/v1/surfaces/{asset} for a surface summary and POST /api/v1/scenarios for price/IV/time P&L scenarios. The API keeps model-status metadata for programmatic consumers; the scanner UI focuses on candidates with positive model edge after costs.

uvicorn options_app.api:create_app --factory --reload

Open http://127.0.0.1:8000/. The screen focuses on candidates with positive model edge after costs and has no order buttons. Historical EV validation is available separately through options_lib.ev_validation.validate_backtest. The evidence helper can be used on timestamped outcomes with options_lib.ev_validation.validate_backtest.

The web app also includes historical options backtesting with explicit exit rules, top-of-book execution costs, trade-level results, unresolved signals, and train/holdout evidence. Configure OPTIONS_BACKTEST_ARCHIVE with a prospectively captured JSONL archive before calling POST /api/v1/backtests. See docs/options-backtest.md for setup and the optional NautilusTrader catalog bridge.

The Position Monitoring workspace is available from the sidebar at #monitoring. Its primary choices are dropdowns for asset, category, observed symbol, and policy preset. The workspace first bootstraps from REST and then uses the server-owned Bybit private WebSocket to track positions, orders, and executions live. It displays deterministic CLOSE, HOLD, or REVIEW decisions and stores immutable reports in SQLite. The WebSocket endpoint is /api/v1/positions/stream; the existing POST /api/v1/positions/monitor endpoint remains available for one-shot API clients. Both paths are read-only: they never submit or close an order; a CLOSE result is a manual instruction that requires human confirmation. Private Bybit credentials are required for live monitoring.

Historical option data is intentionally split by data quality. The BybitPublicClient.get_option_mark_price_history() method downloads historical mark-price candles per option symbol. For complete bid/ask, IV, Greeks, OI, and volume, use BybitOptionSnapshotCollector to capture ticker snapshots prospectively and JsonlOptionSnapshotArchive to persist/replay them. Bybit's public ticker API is latest-only, so the project does not fabricate a historical full-chain snapshot from current data. See docs/option-history.md.

During a scan, the Terminal prints [OPTIONS] progress lines for instrument discovery, ticker loading, market-data normalization, scanner execution, and the final result. Use --log-level info if your Uvicorn configuration hides informational logs. The same progress is shown in the UI's Terminal tiến trình panel while a scan is running.

The API allows local frontend origins (localhost and 127.0.0.1) by default. If the UI is hosted on another origin, configure it as a comma-separated list:

OPTIONS_APP_CORS_ORIGINS=https://your-frontend.example.com uvicorn options_app.api:create_app --factory

Smoke-test it:

trading-mcp            # starts the server (Ctrl-C to stop) — no output is normal; logs go to a file
pytest                 # after: pip install -e ".[dev]"

Use with Claude

The server communicates over stdio, so any MCP client launches it as a subprocess.

Claude Desktop

Edit your MCP config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

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

If trading-mcp isn't on Claude's PATH, use the venv's absolute path instead:

{
  "mcpServers": {
    "trading-mcp": {
      "command": "/abs/path/to/trading-mcp/.venv/bin/trading-mcp"
    }
  }
}

Or run it as a module (no console script needed):

{
  "mcpServers": {
    "trading-mcp": {
      "command": "/abs/path/to/.venv/bin/python",
      "args": ["-m", "mcp_trading"]
    }
  }
}

Restart Claude Desktop — you'll see the 🔌 tools appear. Try: "Use trading-mcp to analyze BTC gamma exposure and the vol surface, then summarize the regime."

Claude Code (CLI)

# from anywhere, register the installed command
claude mcp add trading-mcp -- trading-mcp

# or pin to a specific venv / module form
claude mcp add trading-mcp -- /abs/path/to/.venv/bin/python -m mcp_trading

# with an API key for the position tools (see below)
claude mcp add trading-mcp --env BYBIT_API_KEY=xxx --env BYBIT_API_SECRET=yyy -- trading-mcp

claude mcp list          # verify it's connected

Then in a Claude Code session: "call get_gex_analysis for ETH and explain the key levels."


Keep the session rolling

The single biggest win: don't treat each query as one-shot. Keep one long-lived chat and let market data accumulate in it over time. A single snapshot tells the model where the market is; a session that has seen several snapshots tells it where the market is going — and that's where the analysis gets sharp.

Why it works:

  • Deltas beat levels. "IV is 93%" is noise; "ETH IV went +6.6 pts into an up-move while GEX short gamma halved" is a tradable signal. The model can only compute that second sentence if the earlier snapshot is still in context. See the 2026-06-08 example memos — they're entirely a diff against the 2026-06-07 snapshot taken ~11h earlier.

  • Positions get tracked in time. Re-run the position tools (or paste your book) into the same session and the agent follows each leg across snapshots — PnL drift, greeks decay, whether the original thesis still holds, when premium has bled enough to exit. It remembers what it recommended and grades it.

  • Theses carry forward. The trade ideas, strikes, and risk levels from the first memo become the reference frame for the next one ("the ETH put-spread thesis is stronger now — wider premium, less short gamma, price lifted off support"), instead of starting cold every time.

Practical loop:

  1. Start a memo: "pull BTC + ETH flow, sentiment, technicals, IV-RV and write a market memo."

  2. Hours/days later, in the same chat: "re-pull everything and give me a delta update vs the last snapshot — what changed, and does it change the trade?"

  3. With an API key add: "also pull my positions and track them against the thesis."

A real multi-day position-tracking history (Claude following a book across snapshots) is published here:

→ https://claude.ai/share/cdb4169c-2656-42b9-99e1-6b6b23469ace


Example outputs

The examples/ folder holds real, unedited memos generated through this server:

File

What it is

claude_market_analysis_2026-06-07.md

Full BTC/ETH options memo — snapshot, IV-RV edge, GEX structure, ranked trade ideas

codex_market_analysis_2026-06-07.md

Same day via Codex — straddle/strangle picks with strikes, breakevens, allocation

claude_market_analysis_2026-06-08.md

Delta update ~11h later — a Then → Now → Δ table and what the shifts mean for the thesis

codex_market_analysis_2026-06-08.md

Codex delta update — re-ranked trades, updated allocation, risk controls

The 06-08 files only exist because the 06-07 snapshot was still in the session — that's the rolling workflow above, captured on disk.


API key setup (optional)

Most tools need no credentials — GEX, vanna, skew, flow, vol surface, indicators, klines, funding, OI, options chain, IV-RV, and all strategy-analysis tools use Bybit public market data.

The user-position tools and the read-only monitor_positions tool require a Bybit API key. A read-only key is enough and recommended.

Provide the key by env var (BYBIT_API_KEY, BYBIT_API_SECRET) any of these ways:

# 1) .env file (copy the template, fill in)
cp .env.example .env

# 2) inline in the Claude Desktop config
#    "trading-mcp": { "command": "trading-mcp",
#      "env": { "BYBIT_API_KEY": "xxx", "BYBIT_API_SECRET": "yyy" } }

# 3) Claude Code flags
claude mcp add trading-mcp --env BYBIT_API_KEY=xxx --env BYBIT_API_SECRET=yyy -- trading-mcp

Without a key the position tools return a structured error; everything else works.


The 24 tools

Every tool returns a uniform envelope — { "success": bool, "data": …, "timestamp": … } (or a tool-specific structured object). Defaults shown in ().

Options flow (5)

Tool

Params

Returns

get_gex_analysis

base_coin(BTC), min_oi(1.0)

Gamma-exposure profile: net GEX, gamma walls, flip level, dealer-positioning market impact

get_vanna_analysis

base_coin(BTC), price_move(0.05)

Vanna exposure and the implied-vol impact of a given % price move

get_flow_analysis

base_coin(BTC)

Options flow: volume, put/call ratios, unusual-activity flags

get_skew_analysis

base_coin(BTC)

Volatility skew + term structure across strikes and expiries

get_vol_surface_metrics

base_coin(BTC)

Surface diagnostics: 25Δ risk-reversal, 10Δ skew, vol-of-vol, variance-risk premium

Technical analysis (1)

Tool

Params

Returns

get_technical_indicators

symbol, interval(1h), hours_back(720)

EMA stack, RSI, MACD, ATR, Bollinger, ADX, Hurst exponent, Z-score

Market data (2)

Tool

Params

Returns

get_historical_data

symbol, interval(1h), hours_back(720)

Kline count, latest price, last 10 OHLCV candles

get_options_chain

base_coin(BTC), min_oi(1.0)

Live options chain, OI-filtered, with a sample slice

Sentiment & positioning (3)

Tool

Params

Returns

get_market_sentiment_analysis

symbol(BTCUSDT)

Long/short ratios, positioning bias, sentiment extremes

get_open_interest_analysis

symbol(BTCUSDT)

Open-interest level + trend

get_funding_rate_analysis

symbol(BTCUSDT)

Funding rate, carry cost, funding extremes

Portfolio (2)

Tool

Params

Returns

analyze_portfolio_greeks

portfolio_data

Aggregate Δ/Γ/Θ/Vega + risk metrics for a set of option positions

run_scenario_analysis

portfolio_data, scenarios

Portfolio PnL across supplied price/vol scenarios

Vol selling (2)

Tool

Params

Returns

get_iv_rv_spread

base_coin(BTC), rv_window(30)

ATM implied vol vs Garman-Klass realized vol spread — the vol-selling edge metric

get_covered_call_signal

base_coin(BTC), target_delta(0.10), iv_rv_threshold(10.0), max_dte(14)

Covered-call go/no-go: IV-RV check, vol regime, term structure, skew, recommended OTM strike

Strategy analysis (4)

Tool

Params

Returns

analyze_straddles

base_coin(BTC), min_oi(10.0)

Straddle candidates ranked by profitability

analyze_strangles

base_coin(BTC), min_oi(10.0)

Strangle optimization

analyze_spreads

base_coin(BTC), min_oi(10.0), spread_types([call_spread,put_spread])

Vertical call/put spread analysis

analyze_portfolio_strategies

portfolio_positions

Classifies existing multi-leg strategies in a portfolio (legs, confidence, net cost, breakevens)

User positions (2) — API-key gated

Tool

Params

Returns

get_user_options_positions

base_coin(BTC, or all), position_type(option)

Live option positions + total unrealised PnL

get_user_all_positions

base_coin(BTC), position_type(option/linear/inverse/all)

All positions, per-category breakdown + summary

Position monitoring (2) — API-key gated, read-only

Tool

Params

Returns

monitor_positions

base_coin, position_type, policies

Positions, open orders, order history, and deterministic CLOSE, HOLD, or REVIEW decisions; close instructions require manual confirmation

get_position_monitoring_history

limit(20)

Local append-only monitoring snapshots and the latest PnL/mark/order/decision diff

Meta (1)

Tool

Params

Returns

get_server_info

—

Server name, version, tool count, categories


Bonus: the research prompt

The server also ships one MCP prompt, quant_research_prompt(asset), that primes Claude with a senior-quant options-research workflow — it tells the model which tools to call and how to structure a market memo (snapshot → sentiment/flow → microstructure → strategy proposals → risk checklist). In Claude Desktop it appears in the prompt picker; just pass an asset like BTC.


Configuration

Env var

Default

Purpose

BYBIT_API_KEY / BYBIT_API_SECRET

—

Required for user-position and live monitoring tools (read-only key recommended)

POSITION_MONITORING_SNAPSHOT_FILE

unset

Optional legacy JSONL history path; setting it keeps JSONL compatibility

POSITION_MONITORING_DATABASE

data/position_monitoring/monitoring.sqlite3

SQLite snapshots and raw private-stream events for live monitoring

MCP_LOG_FILE

/tmp/mcp-trading.log

Where the server logs (never stdout — stdio is the JSON-RPC channel)

DEBUG_MCP

unset

Set to 1 for DEBUG-level logs


Safety model

  • Uniform envelope — every tool returns structured {success, data, timestamp}; failures are never free text.

  • Read-first — the analytics surface has no side effects; nothing places or modifies orders.

  • Key-gated — only the position and monitoring tools touch authenticated endpoints; an unconfigured agent physically can't read your book, let alone move money. Use a read-only key.

  • Logs off the wire — MCP uses stdio for JSON-RPC, so all logging is file-only by design.


Architecture

mcp_trading/            thin MCP facade — server.py = 24 @mcp.tool wrappers + 1 prompt
  ├─ orchestrator.py    routes tool calls to the libs; holds the Bybit client + vol analyzer
  ├─ options_lib/       GEX · vanna · skew · flow · vol surface · strategy classification · pricing
  ├─ indicators_lib/    technicals + sentiment
  ├─ portfolio_lib/     portfolio engine · greeks · scenario analysis
  ├─ position_monitoring/ read-only snapshots · risk monitor · manual exit decisions
  └─ bybit_api/         exchange client (klines, options chain, funding, OI, positions)

The facade holds no business logic — it validates inputs (Pydantic models) and delegates. That's why the agent and the bots compute identical numbers from identical code.

License

MIT — see LICENSE.

Available Tools

22 tools
analyze_portfolio_greeksAnalyze Portfolio GreeksC

Analyze portfolio Greeks and risk metrics for options positions

Inputs: params (required). Returns: object

analyze_portfolio_strategiesAnalyze Portfolio StrategiesC

Identify and analyze existing option strategies in portfolio

Inputs: params (required). Returns: object

analyze_spreadsAnalyze SpreadsC

Vertical spread analysis (call and put spreads)

Inputs: params (required). Returns: object

analyze_straddlesAnalyze StraddlesC

Comprehensive straddle analysis with profitability ranking

Inputs: params (required). Returns: object

analyze_stranglesAnalyze StranglesC

Comprehensive strangle analysis with optimization

Inputs: params (required). Returns: object

get_covered_call_signalGet Covered Call SignalA

Evaluate covered call entry signal: go/no-go with IV-RV spread, vol regime, term structure, skew check, and recommended OTM strike

Inputs: params (required). Returns: object

get_flow_analysisGet Flow AnalysisC

Analyze options flow including volume, put/call ratios, and unusual activity

Inputs: params (required). Returns: object

get_funding_rate_analysisGet Funding Rate AnalysisC

Get funding rate analysis and extremes

Inputs: params (required). Returns: object

get_gex_analysisGet Gex AnalysisC

Analyze Gamma Exposure (GEX) levels and market impact

Inputs: params (required). Returns: object

get_historical_dataGet Historical DataC

Get historical price data with basic metrics

Inputs: params (required). Returns: object

get_iv_rv_spreadGet Iv Rv SpreadA

Compute IV-RV spread (ATM implied vol vs Garman-Klass realized vol) — key metric for vol-selling strategies

Inputs: params (required). Returns: object

get_market_sentiment_analysisGet Market Sentiment AnalysisC

Get comprehensive market sentiment analysis including long-short ratios

Inputs: params (required). Returns: object

get_open_interest_analysisGet Open Interest AnalysisC

Get open interest analysis and trends

Inputs: params (required). Returns: object

get_options_chainGet Options ChainC

Get current options chain data

Inputs: params (required). Returns: object

get_server_infoGet Server InfoA

Get server information and available tools

Inputs: no named parameters. Returns: object

get_skew_analysisGet Skew AnalysisC

Analyze volatility skew and term structure across strikes and expiries

Inputs: params (required). Returns: object

get_technical_indicatorsGet Technical IndicatorsB

Calculate technical indicators (RSI, MACD, ATR, Bollinger Bands)

Inputs: params (required). Returns: object

get_user_all_positionsGet User All PositionsB

Get all user positions from Bybit (options, linear, inverse)

Inputs: params (required). Returns: object

get_user_options_positionsGet User Options PositionsB

Get user's options positions from Bybit for any asset (BTC, ETH, SOL)

Inputs: params (required). Returns: object

get_vanna_analysisGet Vanna AnalysisC

Analyze Vanna exposure and volatility impact from price moves

Inputs: params (required). Returns: object

get_vol_surface_metricsGet Vol Surface MetricsB

Get volatility surface diagnostics (RR, skew, vol-of-vol, VRP)

Inputs: params (required). Returns: object

run_scenario_analysisRun Scenario AnalysisC

Run scenario analysis for portfolio PnL across price and volatility moves

Inputs: params (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 22 tools

    Disambiguation4/5

    Most tools map to distinct analytics (straddles vs strangles vs spreads), but two pairs overlap: get_user_options_positions vs get_user_all_positions, and get_skew_analysis vs get_vol_surface_metrics. These could cause misselection, though descriptions clarify the scope.

    Naming Consistency5/5

    All tool names follow a consistent lowercase snake_case verb_noun pattern (get_*, analyze_*, run_*). The prefixes are semantically meaningful and predictable, making it easy to infer tool purpose from the name.

    Tool Count3/5

    22 tools is on the heavier side of typical, but the domain—crypto options analysis with market data, portfolio risk, and strategy tools—can justify the breadth. Still, several tools could be consolidated (e.g., skew/vol-surface overlap), making the set feel slightly over-scoped.

    Completeness4/5

    The set covers the core analysis lifecycle: data retrieval (chain, historical, funding, IV-RV), market analytics (GEX, Vanna, flow, OI), strategy analysis (straddles, strangles, spreads, covered calls), and portfolio risk (Greeks, scenario). It lacks execution/hedging tools, but for an analytics-focused desk that is acceptable; minor gaps like backtesting or strategy comparison remain.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to perform cryptocurrency trading analysis and execution with 38+ tools including real-time market data, technical indicators, risk management, and support for both paper trading and live execution on Hyperliquid.
      7
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      An MCP server that gives an LLM agent a typed, audited tool surface over quant crypto-options desk analytics: gamma exposure, vanna, skew, vol surface, options flow, technicals, portfolio greeks, scenario analysis, and live positions.
      22
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to discover and retrieve options market-structure data (GEX, gamma flip levels, dealer positioning, skew, max pain, expected-move levels, options flow, and ranked trade setups) from Trading Volatility's public API via natural language.
      17
      1
      MIT