{"id":51323892,"url":"https://github.com/dasein108/crypto_options_desk_mcp","last_synced_at":"2026-07-01T16:03:08.281Z","repository":{"id":363229744,"uuid":"1262402710","full_name":"dasein108/crypto_options_desk_mcp","owner":"dasein108","description":"MCP server giving an LLM a typed, read-only tool surface over crypto-options analytics — GEX, vanna, skew, vol surface, greeks, IV-RV, live positions. Point Claude at Bybit data.","archived":false,"fork":false,"pushed_at":"2026-06-08T01:27:59.000Z","size":193,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T03:19:08.424Z","etag":null,"topics":["ai-agent","bybit","claude","crypto","derivatives","gamma-exposure","llm","market-data","mcp","model-context-protocol","options","options-trading","pydantic","python","quantitative-finance","trading","volatility"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dasein108.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-08T00:26:38.000Z","updated_at":"2026-06-08T01:29:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dasein108/crypto_options_desk_mcp","commit_stats":null,"previous_names":["dasein108/crypto_options_desk_mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dasein108/crypto_options_desk_mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dasein108%2Fcrypto_options_desk_mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dasein108%2Fcrypto_options_desk_mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dasein108%2Fcrypto_options_desk_mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dasein108%2Fcrypto_options_desk_mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dasein108","download_url":"https://codeload.github.com/dasein108/crypto_options_desk_mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dasein108%2Fcrypto_options_desk_mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35013184,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","bybit","claude","crypto","derivatives","gamma-exposure","llm","market-data","mcp","model-context-protocol","options","options-trading","pydantic","python","quantitative-finance","trading","volatility"],"created_at":"2026-07-01T16:03:07.418Z","updated_at":"2026-07-01T16:03:08.267Z","avatar_url":"https://github.com/dasein108.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Crypto Options Desk MCP\n\nA **Model Context Protocol (MCP)** server that gives an LLM agent one typed, audited, read-only-by-default\ntool surface over a quant crypto-options desk's analytics: gamma exposure, vanna, skew, vol surface,\noptions flow, technicals, portfolio greeks, scenario analysis, vol-selling signals, and live positions.\n\nPoint Claude (Desktop or Code) at it and ask *\"give me a BTC options market memo\"* — the agent calls the\ntools itself and reasons over real Bybit data.\n\n**What it actually does, end to end:** the LLM drives the whole desk. It calls the flow tools (GEX, vanna,\nskew, vol surface) to read dealer positioning, the sentiment/funding/OI tools to read the crowd, the\ntechnicals for trend, and the IV-RV / vol-selling / strategy tools to find an edge — then it cross-checks\nthose numbers against each other and writes a trader-grade memo: regime call, the structural shifts that\nmatter, defined-risk trade ideas with strikes/breakevens, an allocation, and a risk checklist. With a\nread-only API key it also pulls your live book and folds current positions into the same analysis. The\nmath is identical to what the (private) strategy bots run — the agent just narrates and reasons over it.\n\nSee the [`examples/`](examples/) folder for real outputs: full market memos from both Claude and Codex\n(`*_market_analysis_2026-06-07.md`) and the **delta updates** they produced ~11h later\n(`*_market_analysis_2026-06-08.md`) — each diffs the new snapshot against the prior one (spot, IV, GEX,\nfunding, OI) and tells you what *changed* and why it matters, not just where the market is.\n\n\u003e Extracted from a private multi-strategy trading desk. This is the **analytics surface** only — no\n\u003e strategy signals, thresholds, or alpha. The server is a *thin facade*; all math lives in the bundled\n\u003e libraries (`options_lib`, `indicators_lib`, `portfolio_lib`, `bybit_api`) — the same code the (private)\n\u003e strategy bots import directly. One implementation, surfaced two ways.\n\n---\n\n## Contents\n- [Install](#install)\n- [Use with Claude](#use-with-claude) (Desktop \u0026 Code)\n- [Keep the session rolling](#keep-the-session-rolling) ⭐\n- [Example outputs](#example-outputs)\n- [API key setup](#api-key-setup-optional) (optional)\n- [The 22 tools](#the-22-tools)\n- [Bonus: the research prompt](#bonus-the-research-prompt)\n- [Configuration](#configuration)\n- [Safety model](#safety-model)\n- [Architecture](#architecture)\n\n---\n\n## Install\n\nRequires Python ≥ 3.11.\n\n```bash\n# with uv (recommended)\nuv venv \u0026\u0026 uv pip install -e .\n\n# or plain pip\npip install -e .\n```\n\nThis installs the `trading-mcp` console command (it speaks MCP over stdio).\n\nSmoke-test it:\n\n```bash\ntrading-mcp            # starts the server (Ctrl-C to stop) — no output is normal; logs go to a file\npytest                 # after: pip install -e \".[dev]\"\n```\n\n---\n\n## Use with Claude\n\nThe server communicates over **stdio**, so any MCP client launches it as a subprocess.\n\n### Claude Desktop\n\nEdit your MCP config file:\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"trading-mcp\": {\n      \"command\": \"trading-mcp\"\n    }\n  }\n}\n```\n\nIf `trading-mcp` isn't on Claude's PATH, use the venv's absolute path instead:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"trading-mcp\": {\n      \"command\": \"/abs/path/to/trading-mcp/.venv/bin/trading-mcp\"\n    }\n  }\n}\n```\n\nOr run it as a module (no console script needed):\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"trading-mcp\": {\n      \"command\": \"/abs/path/to/.venv/bin/python\",\n      \"args\": [\"-m\", \"mcp_trading\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop — you'll see the 🔌 tools appear. Try: *\"Use trading-mcp to analyze BTC gamma\nexposure and the vol surface, then summarize the regime.\"*\n\n### Claude Code (CLI)\n\n```bash\n# from anywhere, register the installed command\nclaude mcp add trading-mcp -- trading-mcp\n\n# or pin to a specific venv / module form\nclaude mcp add trading-mcp -- /abs/path/to/.venv/bin/python -m mcp_trading\n\n# with an API key for the position tools (see below)\nclaude mcp add trading-mcp --env BYBIT_API_KEY=xxx --env BYBIT_API_SECRET=yyy -- trading-mcp\n\nclaude mcp list          # verify it's connected\n```\n\nThen in a Claude Code session: *\"call get_gex_analysis for ETH and explain the key levels.\"*\n\n---\n\n## Keep the session rolling\n\n**The single biggest win: don't treat each query as one-shot. Keep one long-lived chat and let market data\naccumulate in it over time.** A single snapshot tells the model where the market *is*; a session that has\nseen several snapshots tells it where the market is *going* — and that's where the analysis gets sharp.\n\nWhy it works:\n\n- **Deltas beat levels.** \"IV is 93%\" is noise; \"ETH IV went +6.6 pts into an up-move while GEX short\n  gamma halved\" is a tradable signal. The model can only compute that second sentence if the earlier\n  snapshot is still in context. See the `2026-06-08` example memos — they're *entirely* a diff against the\n  `2026-06-07` snapshot taken ~11h earlier.\n- **Positions get tracked in time.** Re-run the position tools (or paste your book) into the same session\n  and the agent follows each leg across snapshots — PnL drift, greeks decay, whether the original thesis\n  still holds, when premium has bled enough to exit. It remembers what it recommended and grades it.\n- **Theses carry forward.** The trade ideas, strikes, and risk levels from the first memo become the\n  reference frame for the next one (\"the ETH put-spread thesis is *stronger* now — wider premium, less\n  short gamma, price lifted off support\"), instead of starting cold every time.\n\nPractical loop:\n\n1. Start a memo: *\"pull BTC + ETH flow, sentiment, technicals, IV-RV and write a market memo.\"*\n2. Hours/days later, **in the same chat**: *\"re-pull everything and give me a delta update vs the last\n   snapshot — what changed, and does it change the trade?\"*\n3. With an API key add: *\"also pull my positions and track them against the thesis.\"*\n\nA real multi-day position-tracking history (Claude following a book across snapshots) is published here:\n\n**→ https://claude.ai/share/cdb4169c-2656-42b9-99e1-6b6b23469ace**\n\n---\n\n## Example outputs\n\nThe [`examples/`](examples/) folder holds real, unedited memos generated through this server:\n\n| File | What it is |\n|------|------------|\n| [`claude_market_analysis_2026-06-07.md`](examples/claude_market_analysis_2026-06-07.md) | Full BTC/ETH options memo — snapshot, IV-RV edge, GEX structure, ranked trade ideas |\n| [`codex_market_analysis_2026-06-07.md`](examples/codex_market_analysis_2026-06-07.md) | Same day via Codex — straddle/strangle picks with strikes, breakevens, allocation |\n| [`claude_market_analysis_2026-06-08.md`](examples/claude_market_analysis_2026-06-08.md) | **Delta update** ~11h later — a `Then → Now → Δ` table and what the shifts mean for the thesis |\n| [`codex_market_analysis_2026-06-08.md`](examples/codex_market_analysis_2026-06-08.md) | Codex delta update — re-ranked trades, updated allocation, risk controls |\n\nThe `06-08` files only exist *because* the `06-07` snapshot was still in the session — that's the rolling\nworkflow above, captured on disk.\n\n---\n\n## API key setup (optional)\n\n**Most tools need no credentials** — GEX, vanna, skew, flow, vol surface, indicators, klines, funding,\nOI, options chain, IV-RV, and all strategy-analysis tools use Bybit **public** market data.\n\nOnly the **two user-position tools** (`get_user_options_positions`, `get_user_all_positions`) require a\nBybit API key. A **read-only** key is enough and recommended.\n\nProvide the key by env var (`BYBIT_API_KEY`, `BYBIT_API_SECRET`) any of these ways:\n\n```bash\n# 1) .env file (copy the template, fill in)\ncp .env.example .env\n\n# 2) inline in the Claude Desktop config\n#    \"trading-mcp\": { \"command\": \"trading-mcp\",\n#      \"env\": { \"BYBIT_API_KEY\": \"xxx\", \"BYBIT_API_SECRET\": \"yyy\" } }\n\n# 3) Claude Code flags\nclaude mcp add trading-mcp --env BYBIT_API_KEY=xxx --env BYBIT_API_SECRET=yyy -- trading-mcp\n```\n\nWithout a key the position tools return a structured error; everything else works.\n\n---\n\n## The 22 tools\n\nEvery tool returns a uniform envelope — `{ \"success\": bool, \"data\": …, \"timestamp\": … }` (or a\ntool-specific structured object). Defaults shown in `()`.\n\n### Options flow (5)\n| Tool | Params | Returns |\n|------|--------|---------|\n| `get_gex_analysis` | `base_coin`(BTC), `min_oi`(1.0) | Gamma-exposure profile: net GEX, gamma walls, flip level, dealer-positioning market impact |\n| `get_vanna_analysis` | `base_coin`(BTC), `price_move`(0.05) | Vanna exposure and the implied-vol impact of a given % price move |\n| `get_flow_analysis` | `base_coin`(BTC) | Options flow: volume, put/call ratios, unusual-activity flags |\n| `get_skew_analysis` | `base_coin`(BTC) | Volatility skew + term structure across strikes and expiries |\n| `get_vol_surface_metrics` | `base_coin`(BTC) | Surface diagnostics: 25Δ risk-reversal, 10Δ skew, vol-of-vol, variance-risk premium |\n\n### Technical analysis (1)\n| Tool | Params | Returns |\n|------|--------|---------|\n| `get_technical_indicators` | `symbol`, `interval`(1h), `hours_back`(720) | EMA stack, RSI, MACD, ATR, Bollinger, ADX, Hurst exponent, Z-score |\n\n### Market data (2)\n| Tool | Params | Returns |\n|------|--------|---------|\n| `get_historical_data` | `symbol`, `interval`(1h), `hours_back`(720) | Kline count, latest price, last 10 OHLCV candles |\n| `get_options_chain` | `base_coin`(BTC), `min_oi`(1.0) | Live options chain, OI-filtered, with a sample slice |\n\n### Sentiment \u0026 positioning (3)\n| Tool | Params | Returns |\n|------|--------|---------|\n| `get_market_sentiment_analysis` | `symbol`(BTCUSDT) | Long/short ratios, positioning bias, sentiment extremes |\n| `get_open_interest_analysis` | `symbol`(BTCUSDT) | Open-interest level + trend |\n| `get_funding_rate_analysis` | `symbol`(BTCUSDT) | Funding rate, carry cost, funding extremes |\n\n### Portfolio (2)\n| Tool | Params | Returns |\n|------|--------|---------|\n| `analyze_portfolio_greeks` | `portfolio_data` | Aggregate Δ/Γ/Θ/Vega + risk metrics for a set of option positions |\n| `run_scenario_analysis` | `portfolio_data`, `scenarios` | Portfolio PnL across supplied price/vol scenarios |\n\n### Vol selling (2)\n| Tool | Params | Returns |\n|------|--------|---------|\n| `get_iv_rv_spread` | `base_coin`(BTC), `rv_window`(30) | ATM implied vol vs Garman-Klass realized vol spread — the vol-selling edge metric |\n| `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 |\n\n### Strategy analysis (4)\n| Tool | Params | Returns |\n|------|--------|---------|\n| `analyze_straddles` | `base_coin`(BTC), `min_oi`(10.0) | Straddle candidates ranked by profitability |\n| `analyze_strangles` | `base_coin`(BTC), `min_oi`(10.0) | Strangle optimization |\n| `analyze_spreads` | `base_coin`(BTC), `min_oi`(10.0), `spread_types`([call_spread,put_spread]) | Vertical call/put spread analysis |\n| `analyze_portfolio_strategies` | `portfolio_positions` | Classifies existing multi-leg strategies in a portfolio (legs, confidence, net cost, breakevens) |\n\n### User positions (2) — *API-key gated*\n| Tool | Params | Returns |\n|------|--------|---------|\n| `get_user_options_positions` | `base_coin`(BTC, or `all`), `position_type`(option) | Live option positions + total unrealised PnL |\n| `get_user_all_positions` | `base_coin`(BTC), `position_type`(option/linear/inverse/all) | All positions, per-category breakdown + summary |\n\n### Meta (1)\n| Tool | Params | Returns |\n|------|--------|---------|\n| `get_server_info` | — | Server name, version, tool count, categories |\n\n---\n\n## Bonus: the research prompt\n\nThe server also ships one MCP **prompt**, `quant_research_prompt(asset)`, that primes Claude with a\nsenior-quant options-research workflow — it tells the model which tools to call and how to structure a\nmarket memo (snapshot → sentiment/flow → microstructure → strategy proposals → risk checklist). In Claude\nDesktop it appears in the prompt picker; just pass an asset like `BTC`.\n\n---\n\n## Configuration\n\n| Env var | Default | Purpose |\n|---------|---------|---------|\n| `BYBIT_API_KEY` / `BYBIT_API_SECRET` | — | Only for the two user-position tools (read-only key recommended) |\n| `MCP_LOG_FILE` | `/tmp/mcp-trading.log` | Where the server logs (never stdout — stdio is the JSON-RPC channel) |\n| `DEBUG_MCP` | unset | Set to `1` for DEBUG-level logs |\n\n---\n\n## Safety model\n\n- **Uniform envelope** — every tool returns structured `{success, data, timestamp}`; failures are never free text.\n- **Read-first** — the analytics surface has no side effects; nothing places or modifies orders.\n- **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.\n- **Logs off the wire** — MCP uses stdio for JSON-RPC, so all logging is file-only by design.\n\n---\n\n## Architecture\n\n```\nmcp_trading/            thin MCP facade — server.py = 22 @mcp.tool wrappers + 1 prompt\n  ├─ orchestrator.py    routes tool calls to the libs; holds the Bybit client + vol analyzer\n  ├─ options_lib/       GEX · vanna · skew · flow · vol surface · strategy classification · pricing\n  ├─ indicators_lib/    technicals + sentiment\n  ├─ portfolio_lib/     portfolio engine · greeks · scenario analysis\n  └─ bybit_api/         exchange client (klines, options chain, funding, OI, positions)\n```\n\nThe facade holds **no business logic** — it validates inputs (Pydantic models) and delegates. That's why\nthe agent and the bots compute identical numbers from identical code.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdasein108%2Fcrypto_options_desk_mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdasein108%2Fcrypto_options_desk_mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdasein108%2Fcrypto_options_desk_mcp/lists"}