Model Context Protocol Server

Trading Volatility MCP

A read-only MCP server that gives AI agents conversational access to equity options & volatility market-structure data from Trading Volatility. It is a stateless passthrough over the v2 REST API — it retrieves data only; it never places orders or handles payments.

16 tools Read-only stdio + Streamable HTTP FastMCP · Python v0.1.0

Domain: gamma exposure (GEX), gamma flip levels, dealer positioning, volatility skew, IV rank, max pain, expected-move levels, options flow/volume, and ranked trade setups. The same intelligence served by the v2 API, exposed as agent-callable tools.

Quick Setup — any MCP-capable assistant

1 · Add the server

Drop this into your client's MCP config — Claude Desktop, Cursor, Windsurf, VS Code, or any MCP-capable agent. Points at the hosted endpoint; your key rides along as a header.

{
  "mcpServers": {
    "trading-volatility": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://tv-mcp-avhwfkn5gq-uc.a.run.app/mcp",
        "--header",
        "Authorization: Bearer YOUR_TV_API_KEY"
      ]
    }
  }
}

Prefer local? Skip the network — run it over stdio straight from PyPI:

{
  "mcpServers": {
    "trading-volatility": {
      "command": "uvx",
      "args": ["tv-mcp"],
      "env": { "TV_API_KEY": "YOUR_TV_API_KEY" }
    }
  }
}

Your personal API key is available once you subscribe. No key yet? Leave it out — demo mode works out of the box for AAPL · VIX · KO · META · AMZN · XOM · GM · MCD. Then restart your client.

2 · Just ask

"What's NVDA's gamma regime and key levels today?"
"Where is TSLA's gamma flip and max pain right now?"
"Rank the top 5 bullish trade setups across all tickers"
"Show me the GEX-by-strike curve for SPY"
"Run the capitulation-reversal screener"
"Explain AMZN's current options positioning"
"Pull 180 days of IV-rank history for META"

Capabilities — 16 tools + 1 resource

Meta / Auth

server_info

Returns the server name and version string.

get_auth_status

Reports whether the session is keyed (full access) or demo mode; never reveals the key.

list_capabilities

Returns the full /llm-spec manifest (endpoints, metrics, regimes, screeners). Call first to self-orient.

Ticker State

get_ticker_state

Compact state snapshot — price, gamma regime, IV rank, key positioning metrics.

ticker · include (optional CSV add-ons)

explain_ticker

Deterministic plain-language narrative of the current regime and positioning.

ticker · view (optional)

get_market_structure

Assembled read — headline signal, regime classification, expected behavior, key levels.

ticker · include (optional CSV sections)

get_signals

Current active setup / positioning signals for a ticker.

ticker

get_levels

Key price levels — gamma flip, walls, max pain, expected-move bounds.

ticker · view (json / tradingview / tos)

Curves & Series

get_series

Historical daily time series for charting and regime context.

ticker · metrics (CSV) · window (e.g. 30d, 180d, 2y)

get_gamma_curve

Gamma strike curve (net gamma per strike).

ticker · exp · realtime (optional)

get_gamma_by_expiration

Strike-aligned gamma decomposition broken out by expiration bucket.

ticker

get_gex_by_strike

Net GEX strike curve with call/put contributions — key strikes and call vs. put dominance.

ticker · exp (optional)

get_options_volume

Real-time options volume aggregated by strike for a specific expiration.

ticker · exp (required) · include (iv)

Discovery / Ranking

rank_top_setups

Ranks trade setups across all tickers by opportunity score.

All optional: limit · min_score · regime · recommended_direction · iv_rank_min/max · price_min/max · momentum / trend / vol filters

run_screener

Runs a named thesis preset over the cross-ticker ranking.

name (momentum_breakout, capitulation_reversal, range_premium_seller, trend_pullback, highvol_breakdown) · same optional filters

get_trade_setup

Compact agent-oriented setup for one ticker — regime, bias, score/tier, trade type, direction, structures, entry/stop/target framing, caution flags.

ticker

Resource

tv://llm-spec

The v2 capability manifest as application/json — mirrors list_capabilities for clients that browse resources rather than call tools.

No MCP prompts are defined.

Use Cases

Conversational options analysis — ask an agent about a ticker's gamma regime, key levels, or volatility state without opening a browser.
Opportunity screening — use rank_top_setups or run_screener to surface the highest-scoring setups across all tickers, filtered by regime, direction, IV rank, and price.
Agent-ready trade framing — get_trade_setup returns a complete structured recommendation (direction, structures, entry/stop/target).
Historical context & charting — pull multi-metric time series for regime history and IV-rank trends.
Strike-level gamma / GEX analysis — identify dealer hedging pressure points, call/put dominance, and expiration-level gamma decomposition.
Multi-framework integration — works with Claude, OpenAI Responses API, Google ADK, LangChain/LangGraph, and Vercel AI SDK over standard streamable-HTTP MCP.

Access Model

Transports	`stdio` (local, default) and Streamable HTTP + SSE (hosted, at `/mcp`).
Auth	Per-request `Authorization: Bearer <key>` or `X-Api-Key`, forwarded to the v2 API, never persisted. Fallback: header → `TV_API_KEY` → `config.json` → demo. Keys are issued on subscription.
Demo mode	No key required for 8 tickers: AAPL, VIX, KO, META, AMZN, XOM, GM, MCD.
HTTP routes	`/health` · `/healthz` · `/AGENTS.md` (agent discovery).
Discovery	Server card at `/.well-known/mcp-server-card.json`.

Architecture

agent ──tools──▶ TV MCP (stateless) ──HTTPS Bearer──▶ stocks.tradingvolatility.net/api/v2

Prefer raw HTTP?

The MCP server wraps the same data as the v2 REST API. Browse endpoints and try them live there, or hand an agent the /api/v2/llm-spec manifest directly.