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

• Install

• Use with Claude (Desktop & Code)

• Keep the session rolling ⭐

• Example outputs

• API key setup (optional)

• The 22 tools

• Bonus: the research prompt

• Configuration

• Safety model

• Architecture

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).

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:

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.

Only the two user-position tools (get_user_options_positions, get_user_all_positions) 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 22 tools

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

Options flow (5)

Technical analysis (1)

Market data (2)

Sentiment & positioning (3)

Portfolio (2)

Vol selling (2)

Strategy analysis (4)

User positions (2) — API-key gated

Meta (1)

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

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 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 = 22 @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
  └─ 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.