Crypto Options Desk MCP
This server is an MCP tool surface for quant crypto-options analytics, letting AI agents pull live Bybit market data and portfolio insights to produce desk-style research and trade memos.
Options flow analytics: gamma exposure (GEX), vanna, flow/put-call ratios, volatility skew, and vol surface diagnostics.
Technical and market data: indicators (RSI, MACD, ATR, Bollinger), historical klines, and full options chain data.
Sentiment and positioning: long/short ratios, open interest trends, and funding rate analysis.
Portfolio analytics: aggregate Greeks, scenario P&L, and existing multi-leg strategy classification.
Vol-selling signals: IV-RV spread and covered-call go/no-go evaluation with recommended strikes.
Strategy analysis: ranked straddles, strangles, and vertical spreads.
User positions (API-key gated): live option/all positions with PnL, plus read-only deterministic position monitoring (CLOSE/HOLD/REVIEW) and monitoring history.
Meta: server info with tool count and categories.
Read-only by default: analytics only; no order placement or modification.
Click on "Deploy 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., "@Crypto Options Desk MCP Give me a BTC options market memo for today."
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.
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
Use with Claude (Desktop & Code)
API key setup (optional)
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 --reloadOpen 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 --factorySmoke-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.jsonWindows:
%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 connectedThen 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-08example memos — they're entirely a diff against the2026-06-07snapshot 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:
Start a memo: "pull BTC + ETH flow, sentiment, technicals, IV-RV and write a market memo."
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?"
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 |
Full BTC/ETH options memo — snapshot, IV-RV edge, GEX structure, ranked trade ideas | |
Same day via Codex — straddle/strangle picks with strikes, breakevens, allocation | |
Delta update ~11h later — a | |
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-mcpWithout 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 |
|
| Gamma-exposure profile: net GEX, gamma walls, flip level, dealer-positioning market impact |
|
| Vanna exposure and the implied-vol impact of a given % price move |
|
| Options flow: volume, put/call ratios, unusual-activity flags |
|
| Volatility skew + term structure across strikes and expiries |
|
| Surface diagnostics: 25Δ risk-reversal, 10Δ skew, vol-of-vol, variance-risk premium |
Technical analysis (1)
Tool | Params | Returns |
|
| EMA stack, RSI, MACD, ATR, Bollinger, ADX, Hurst exponent, Z-score |
Market data (2)
Tool | Params | Returns |
|
| Kline count, latest price, last 10 OHLCV candles |
|
| Live options chain, OI-filtered, with a sample slice |
Sentiment & positioning (3)
Tool | Params | Returns |
|
| Long/short ratios, positioning bias, sentiment extremes |
|
| Open-interest level + trend |
|
| Funding rate, carry cost, funding extremes |
Portfolio (2)
Tool | Params | Returns |
|
| Aggregate Δ/Γ/Θ/Vega + risk metrics for a set of option positions |
|
| Portfolio PnL across supplied price/vol scenarios |
Vol selling (2)
Tool | Params | Returns |
|
| ATM implied vol vs Garman-Klass realized vol spread — the vol-selling edge metric |
|
| Covered-call go/no-go: IV-RV check, vol regime, term structure, skew, recommended OTM strike |
Strategy analysis (4)
Tool | Params | Returns |
|
| Straddle candidates ranked by profitability |
|
| Strangle optimization |
|
| Vertical call/put spread analysis |
|
| Classifies existing multi-leg strategies in a portfolio (legs, confidence, net cost, breakevens) |
User positions (2) — API-key gated
Tool | Params | Returns |
|
| Live option positions + total unrealised PnL |
|
| All positions, per-category breakdown + summary |
Position monitoring (2) — API-key gated, read-only
Tool | Params | Returns |
|
| Positions, open orders, order history, and deterministic |
|
| Local append-only monitoring snapshots and the latest PnL/mark/order/decision diff |
Meta (1)
Tool | Params | Returns |
| — | 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 |
| — | Required for user-position and live monitoring tools (read-only key recommended) |
| unset | Optional legacy JSONL history path; setting it keeps JSONL compatibility |
|
| SQLite snapshots and raw private-stream events for live monitoring |
|
| Where the server logs (never stdout — stdio is the JSON-RPC channel) |
| unset | Set to |
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 toolsanalyze_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
Scored across 22 tools
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.
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.
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.
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
Related MCP Connectors
Options flow, volatility, dealer positioning (GEX) and dark pool data for AI trading agents.
Market analyst tools + AI agent: crypto, US equities, options, Korea, fundamentals, macro, backtests
Web search, point-in-time crypto market data, verified strategy track records and 160+ agent tools.
Calibrated world model for AI agents. 40 tools: world state, markets, trading. Kalshi + Polymarket.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.7MIT
- AlicenseBqualityCmaintenanceAn 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.222MIT
- AlicenseAqualityDmaintenanceEnables 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.171MIT
- AlicenseCqualityDmaintenanceEnables LLMs to interact with Bybit V5 API for market data, trading, account management, and position tracking.937 npmMIT