Integrates with Google Gemini, allowing Gemini agents to discover and retrieve options and volatility market data via the Trading Volatility MCP server.
Integrates with LangChain, enabling LangChain agents to use MCP tools for querying options market structure, signals, and levels from Trading Volatility.
Integrates with LangGraph, allowing LangGraph agents to retrieve options market data including gamma curves, GEX by strike, and trade setups.
Integrates with OpenAI's platform, enabling agents to access Trading Volatility's options market data, including expected move, max pain, and rank trade setups.
Integrates with Vercel AI SDK, enabling AI applications on Vercel to access Trading Volatility's options and volatility data through the MCP server.
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., "@Trading Volatility MCP show me gamma levels for AAPL"
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.
The options & volatility data source agents can query.
A Model Context Protocol server for Trading Volatility — lets any AI agent 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) over the public v2 API, in conversation.
Read-only — discovers and retrieves data over your existing Trading Volatility subscription. No orders, payments, or monitoring.
Stateless passthrough — forwards your Authorization: Bearer <key> to the v2 API and
stores nothing. Local and hosted modes are the same code path.
Two transports — stdio for local agents, streamable HTTP + SSE for remote,
multi-user hosting.
Works without a key — the demo tickers (AAPL, VIX, KO, META, AMZN, XOM, GM, MCD) work out of the box.
Tool | What it returns |
| The v2 capability manifest ( |
| Whether you're in keyed or demo mode |
| Canonical compact state snapshot |
| Deterministic narrative interpretation of the regime |
| Headline signal, regime, expected behavior, levels |
| Current setup/positioning signals |
| Key levels (json / tradingview / tos) |
| Historical daily series for selected metrics over a window |
| Gamma strike curve (per expiration, optionally realtime) |
| Gamma decomposition by expiration bucket |
| Net GEX strike curve with call/put contributions |
| Options volume by strike for an expiration |
| Cross-ticker opportunity ranking, with filters |
| A named thesis preset over the ranking |
| Cross-ticker covered-call / cash-secured-put ranking, with filters |
| Compact agent-oriented trade setup for one ticker |
Related MCP server: FlashAlpha MCP Server
# Run straight from PyPI with uvx (or: pipx run tv-mcp)
uvx tv-mcp # stdio; uses TV_API_KEY or a config file
# …or from source
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
cp config.example.json config.json # add your API key (git-ignored)
python -m tv_mcp # stdio by defaultValidate:
ruff check . && pytestThe key is resolved in this order (first match wins):
Per-request header — Authorization: Bearer <key> (or X-Api-Key) — hosted mode.
Environment — TV_API_KEY.
Local JSON config — tv_api_key in config.json (see config.example.json; values
support ${ENV_VAR} substitution so the key can stay in the environment).
Demo mode — no key; only the demo tickers are available.
The key is never logged or persisted.
TV_MCP_TRANSPORT=http PORT=8000 python -m tv_mcp # serves http://0.0.0.0:8000/mcpEach request carries its own key, so one deployment serves many users:
POST /mcp Authorization: Bearer <your-key>
GET /health liveness probe
GET /AGENTS.md agent-discovery doc (how to use this server)Container build (binds $PORT, runs the HTTP transport — deploys to any container host such
as Cloud Run, Fly, or ECS):
docker build -t tv-mcp .
docker run -p 8080:8080 tv-mcpThe server is stateless and holds no secrets, so it scales horizontally with no extra setup;
tune limits with the env vars in .env.example.
Claude Code / Claude Desktop (local, stdio) — claude_desktop_config.json:
{
"mcpServers": {
"trading-volatility": {
"command": "uvx",
"args": ["tv-mcp"],
"env": { "TV_API_KEY": "your-key" }
}
}
}Remote MCP clients (Claude web custom integrations, OpenAI Responses mcp tool, Gemini
function-calling, the Vercel AI SDK, ADK's MCPToolset, LangChain/LangGraph's
MultiServerMCPClient) all point at the same endpoint and pass the key as a header:
URL: https://<your-deployment>/mcp
Header: Authorization: Bearer <your-key>
Because the server is a standard streamable-HTTP MCP endpoint with header auth, no per-client shim is needed — configure the URL and header in whichever framework you use. Copy-pasteable guides with real code for each:
Anthropic Claude — Claude Code, Desktop, the Messages API MCP connector, and Claude web
OpenAI · Google Gemini · Google ADK · LangChain/LangGraph · Vercel AI SDK
Index: docs/integrations/
agent ──tools──▶ TV MCP ──HTTPS (Bearer key)──▶ stocks.tradingvolatility.net/api/v2
(stateless)The agent carries continuity between turns; the server keeps no session state. It forwards the caller's key and returns the v2 payloads unchanged (they are already agent-shaped).
src/tv_mcp/
cli.py stdio | http entry point
server.py FastMCP wiring (tools, resources, /health, /AGENTS.md)
settings.py config loading + precedence
auth.py credential resolution (header → env → config → demo)
tv/ v2 API client + normalized errors
tools/ one module per tool group (tickers, curves, discovery, auth)
transports/ stateless HTTP + SSE app, per-request key middleware
tests/ client, auth, settings, tools, transport, smoke
docs/ design, build plan, implementation notesdocs/integrations/ — per-framework integration guides
(Claude, OpenAI, Gemini, ADK, LangChain, AI SDK)
Deployment runbooks and maintainer planning artifacts are kept internal and excluded from public releases.
MIT — see LICENSE. Open source under the Trading Volatility brand.
Get a deterministic narrative interpretation of a ticker's current regime and positioning — a plain-language read of the state. Optional view selects an alternate explanation view when available.
Inputs: ticker (required), view. Returns: object
Check how the Trading Volatility MCP is authenticated for this session. Returns mode='keyed' when an API key is present (full access), or mode='demo' when no key is set (only the demo tickers are available). Does not reveal the key.
Inputs: no named parameters. Returns: object
Get the strike-aligned gamma decomposition by expiration bucket for a ticker (combined, nearest, first_weekly, first_monthly, all_other_expiries).
Inputs: ticker (required). Returns: object
Get the gamma strike curve (net gamma per strike) for a ticker. exp selects the expiration: 'combined' (default), 'nearest', 'first_weekly', 'first_monthly', or a 'YYYY-MM-DD' date. Set realtime=true for an intraday pull (requires trading hours when exp is a specific date).
Inputs: ticker (required), exp, realtime. Returns: object
Get the net GEX (gamma exposure) strike curve for a ticker, with call/put contributions — identifies key strikes and call-vs-put dominance. exp selects the expiration: 'combined' (default), 'nearest', or 'first_monthly'.
Inputs: ticker (required), exp. Returns: object
Get key price levels for a ticker (gamma flip, walls, max pain, expected-move bounds). Optional view formats the output: 'json' (default), 'tradingview', or 'tos' (thinkorswim).
Inputs: ticker (required), view. Returns: object
Get the assembled market-structure interpretation for a ticker: headline signal, regime classification, expected behavior, key levels, and supporting metrics. Optional include adds sections (e.g. 'state', 'call_diag').
Inputs: ticker (required), include. Returns: object
Get real-time options volume aggregated by strike for a ticker and a specific expiration. exp (the expiration date, required) selects the contract month; set include='iv' to add implied-volatility columns.
Inputs: exp (required), ticker (required), include. Returns: object
Get a historical daily time series for a ticker, for charting and regime context. metrics is a comma-separated list of metric keys (e.g. 'price,iv_rank,gex_flip'); window is a lookback like '30d', '180d', or '2y'. Both are optional and fall back to the API defaults.
Inputs: ticker (required), window, metrics. Returns: object
Get the current signals for a ticker (active setup/positioning signals).
Inputs: ticker (required). Returns: object
Get the canonical compact state snapshot for a ticker — the default starting point for analysis (price, gamma regime, IV rank, key positioning metrics). Optional include is a comma-separated list of add-ons (e.g. 'call_diag').
Inputs: ticker (required), include. Returns: object
Get the compact agent-oriented trade setup for a ticker: market state plus a deterministic trade recommendation (regime, bias, opportunity score/tier, trade type, direction, structures, entry/stop/target framing, and caution flags).
Inputs: ticker (required). Returns: object
Return the Trading Volatility v2 capability manifest (the /llm-spec): the full list of endpoints, metrics, parameters, and conventions. Call this first to self-orient — to discover which metrics, expirations, regimes, and screeners are available before making other calls.
Inputs: no named parameters. Returns: object
Rank single-leg income setups (covered calls and cash-secured puts) across all tickers by an IVR-led, regime-guarded income-fit score (descending). Each ticker may surface as both a CC and a CSP candidate, each with a 1-sigma suggested strike, estimated premium, annualized yield, assignment/cap price, and breakeven. Filters (all optional): type ('cc' or 'csp'; omit for both), min_income_score (0-10), limit (2-50, default 10). Estimates are as-of the latest snapshot; earnings/event risk is flagged in each row's caveats but not filtered out.
Inputs: type, limit, min_income_score. Returns: object
Rank trade setups across all tickers by opportunity score (descending) to discover opportunities. Filters (all optional, AND'd): limit (1-200, default 20), min_score (0-10), regime (CSV of RegimeLabel values like 'trending_low_vol,range_bound'), recommended_direction (CSV of long/short/neutral), trade_bias, trend_state, momentum_state, realized_vol_state (CSV), iv_rank_min/iv_rank_max (0-100), price_min/price_max.
Inputs: limit, regime, min_score, price_max, +8 more. Returns: object
Run a named screener preset over the cross-ticker ranking. name is one of: momentum_breakout, capitulation_reversal, range_premium_seller, trend_pullback, highvol_breakdown. Any filter you pass overrides the preset's value. Filters (all optional, AND'd): limit (1-200, default 20), min_score (0-10), regime (CSV of RegimeLabel values like 'trending_low_vol,range_bound'), recommended_direction (CSV of long/short/neutral), trade_bias, trend_state, momentum_state, realized_vol_state (CSV), iv_rank_min/iv_rank_max (0-100), price_min/price_max.
Inputs: name (required), limit, regime, min_score, +9 more. Returns: object
Basic information about this MCP server.
Inputs: no named parameters. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 17 tools
Several tools target the same ticker and provide overlapping market-state information (get_ticker_state, get_market_structure, get_trade_setup, explain_ticker). While each has a distinct output format, the boundaries are not immediately clear from names alone. Gamma curve and GEX curve tools also overlap conceptually.
All tools use snake_case with verb-first names (get_, rank_, run_, explain_, list_), and server_info is the only exception but still follows a predictable pattern. Very consistent and easy to parse.
17 tools is on the heavy side but justifiable for a comprehensive volatility analytics API covering per-ticker analysis, cross-ticker ranking, screeners, and income setups. The count is slightly above the ideal range but not bloated.
The server covers a wide range of analysis needs: state snapshots, narratives, signals, levels, historical series, gamma/GEX curves, options volume, rankings, screeners, and trade setups. Minor gaps like open interest or an IV surface exist, but they are not critical for its stated purpose.
Options flow, volatility, dealer positioning (GEX) and dark pool data for AI trading agents.
Options analytics for AI assistants: chains, IV rank, VRP, Greeks, GEX, expected moves, screeners.
The full TraderMatrix market-data connector for Claude, Cursor and any MCP client. 51 tools: scored and tiered unusual options activity, dealer gamma (GEX), Apex levels and gamma pockets, IV rank, sector flow, dark-pool net-notional rollups, market health and macro regime, gap-continuation and breakout signals, wheel and CSP screeners, a one-call ticker snapshot, and your own watchlists. Needs a TraderMatrix API key (OAuth sign-in works for Claude web and mobile). A free, no-key connector with the gapper scanner and Market Health tools is listed separately as TraderMatrix Free.
Real-time & historical options analytics: GEX, dealer positioning, vol, VRP, 0DTE, CME futures
