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., "@greeks-mcp show me GEX and max pain for SPY"
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.
A Model Context Protocol server that exposes the Greeks options-analytics API as tools for any MCP client — Claude Desktop, Cursor, Claude Code, and more. Ask your assistant for GEX, Greeks, Max Pain, unusual flow or a full dashboard on any ticker and it pulls live from the API.
Only derived/computed analytics are exposed — no raw market data is redistributed.
1. Get an API key. Sign up at greeks.pro and create a key
— it looks like grk_<48 hex>. Public tools (screener, health, plans) work without
one.
2. Add one block to your client config and restart the client:
{
"mcpServers": {
"greeks-analytics": {
"command": "uvx",
"args": ["greeks-mcp"],
"env": { "GREEKS_API_KEY": "grk_your_key_here" }
}
}
}That's it — the assistant now has all 17 tools. uv
downloads and runs the published package on demand in an isolated environment, so
there's nothing to install or keep updated by hand.
Prefer pipx? pipx install greeks-mcp, then use "command": "greeks-mcp" with no
args.
A Dockerfile is included for containerized runs. The server speaks stdio (what
MCP clients spawn), so run it interactively (-i):
docker build -t greeks-mcp .
docker run --rm -i -e GREEKS_API_KEY=grk_your_key_here greeks-mcpThe image starts and answers MCP introspection (initialize + tools/list) with
no key; GREEKS_API_KEY is only needed for the authenticated analytics tools.
To wire the container into an MCP client, set "command": "docker" with
"args": ["run","--rm","-i","-e","GREEKS_API_KEY","greeks-mcp"].
The same mcpServers block works in every MCP client — only the file location
differs.
Client | Config file |
Claude Desktop (macOS) |
|
Claude Desktop (Windows) |
|
Cursor (global) |
|
Cursor (per-project) |
|
Ready-to-copy configs live in examples/. After reloading, the server
shows up under Cursor's Settings → MCP with a green dot and its 17 tools; type
@greeks-analytics in chat (or just ask for GEX/greeks/max pain) to use them.
Related MCP server: options-chain-mcp
Tool | Endpoint | Min plan | What it returns |
|
| Free | Max Pain strike per expiration |
|
| Trader | Δ Γ Θ V ρ, theo price, mispricing per contract |
|
| Trader | GEX/DEX per strike, total Net GEX, Gamma Flip |
|
| Trader | Unusual-activity signals |
|
| Trader | IV skew + term structure with plain-English reads |
|
| Pro | Full dashboard (sentiment, GEX, max pain, expected move, IV surface, term structure, top flow) |
|
| Pro | Vanna & Charm exposure (2nd-order dealer Greeks) |
|
| Pro | 0DTE focus panel — pin risk, gamma flip, max pain |
|
| Pro | Intraday gamma-regime time-series + flip timing |
|
| Pro | Day-by-day level outcomes (the receipts behind the %) |
|
| — | Compact analytics snapshot |
|
| — | Options-derived support/resistance levels |
|
| public | Watchlist screener — discover interesting symbols |
|
| public | GEX-by-strike heatmap for a watchlist symbol |
|
| public | Aggregated signal accuracy (~last 35 days) |
|
| public | Plans, prices, limits, routes |
|
| public | Service health |
Most analytics tools take symbol (required) and optional expiration (a Unix
timestamp, or "all" for every expiration; omit for the nearest expiry).
get_greeks also accepts range="atm", moneyness="low,high" and limit.
Two take different args: get_gex_intraday uses date="YYYY-MM-DD" (not
expiration), and get_track_record_detail takes an optional symbol only.
Env var | Required | Default | Description |
| for | — | Your |
| no |
| API base URL |
| no |
| Per-request timeout (s) |
| no |
|
|
Requires Python ≥ 3.10.
git clone https://github.com/ArtBreguez/greeks-mcp.git
cd greeks-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# stdio (what MCP clients spawn)
GREEKS_API_KEY=grk_... greeks-mcp # or: python -m greeks_mcp
# or over HTTP
GREEKS_API_KEY=grk_... MCP_TRANSPORT=http greeks-mcp# Inspect the tools interactively without a full client:
mcp dev src/greeks_mcp/server.py
# Tests (no network needed):
python tests/test_server.py # tool wiring (URLs, params, headers, errors)
python tests/test_e2e.py # spawns the server over stdio, calls all 17 toolsPublished to PyPI via Trusted Publishing (OIDC — no API token stored). One-time setup:
On PyPI → Account settings → Publishing → add a pending publisher:
project greeks-mcp, owner ArtBreguez, repo greeks-mcp, workflow
publish.yml, environment pypi.
In GitHub repo settings → Environments, create an environment named pypi.
Then cut a release by bumping version in pyproject.toml + __init__.py and
pushing a tag:
git tag v0.1.0 && git push origin v0.1.0The workflow builds the sdist+wheel, verifies the wheel installs and registers all 17 tools, and publishes.
Plans & errors: a 402/403 means your plan doesn't include that route (or
you hit the symbol/rate limit). Call list_plans to see what each tier unlocks.
expiration="all" returns every expiration — richer but slower. For heavy
names prefer a specific expiration timestamp, or raise GREEKS_TIMEOUT.
Derived data only. No raw market data (quotes, bid/ask, OI, contract prices) is redistributed — everything here is computed analytics.
MIT — see LICENSE.
Unusual options activity detection — contracts with abnormally high volume relative to open interest, typically signalling institutional/"smart money" positioning.
Signals: unusual_volume (high: Vol/OI ≥ 3.0, medium: ≥ 1.5) and opening_position (Vol ≥ 50 with OI = 0). Contracts with volume < 10 are noise.
Plan: Trader and up.
Args: symbol: Underlying ticker. expiration: Unix timestamp of a specific expiry, or "all". Omit for the nearest expiry.
Returns FlowResponse JSON: symbol, spotPrice, timestamp, and signals[] each with contractSymbol, type, strike, expiration, dte, volumeOIRatio, iv, signal, severity.
Inputs: symbol (required), expiration.
Gamma & Delta Exposure (GEX/DEX) per strike, plus total Net GEX and the Gamma Flip level (strike where Net GEX crosses zero — a regime transition). Positive Net GEX = dealers long gamma (price pins); negative = moves amplified.
Plan: Trader and up.
Args:
symbol: Underlying ticker.
expiration: Unix timestamp of a specific expiry, or "all". Omit for the
nearest expiry.
symbols: Optional comma-separated list for a multi-symbol GEX request
(e.g. "SPY,QQQ,IWM"); when set it takes precedence over symbol.
Returns GEXResponse JSON: symbol, spotPrice, timestamp, totalNetGEX, gammaFlip, and strikes[] with callGEX/putGEX/netGEX and callDEX/putDEX/netDEX.
Inputs: symbol (required), symbols, expiration.
Black-Scholes Greeks (Delta, Gamma, Theta, Vega, Rho) plus theoretical price and mispricing for every contract in the chain.
Plan: Trader and up.
Args: symbol: Underlying ticker. expiration: Unix timestamp of a specific expiry, or "all". Omit for the nearest expiry. range: Pass "atm" to restrict the chain to at-the-money contracts. moneyness: A "low,high" pair (e.g. "0.9,1.1") to filter contracts by strike/spot ratio. limit: Cap the number of contracts returned (per side).
Returns GreeksResponse JSON: symbol, spotPrice, timestamp, and contracts[] each with delta/gamma/theta/vega/rho, iv, theoreticalPrice, mispricing, inTheMoney.
Inputs: symbol (required), limit, range, moneyness, +1 more.
Key options-derived price levels for a symbol (support/resistance style levels from gamma and open-interest structure).
Args: symbol: Underlying ticker. expiration: Unix timestamp of a specific expiry, or "all". Omit for the nearest expiry.
Returns the LevelsResponse JSON as computed by the analytics engine.
Inputs: symbol (required), expiration.
Max Pain per expiration — the strike that minimizes total option value (where most options expire worthless), a magnet the price tends to converge toward at expiration.
Plan: Free (1 symbol, 15-min delay) and up.
Args: symbol: Underlying ticker, e.g. "AAPL", "SPY", "NDAQ". expiration: Unix expiration timestamp for a single expiry, or "all" for every expiration (slower, complete). Omit for the nearest expiry.
Returns the raw MaxPainResponse JSON: symbol, spotPrice, timestamp, and results[] with maxPainStrike, totalPainAtMax, spotDistance, spotDistancePct.
Inputs: symbol (required), expiration.
Full analytics dashboard for a symbol in one call: sentiment, GEX summary, max pain, expected moves, IV surface, term structure and top unusual flow. The cheapest way to get everything for a symbol at once.
Plan: Pro and up.
Args: symbol: Underlying ticker. expiration: Unix timestamp of a specific expiry, or "all" (recommended for the full dashboard). Omit for the nearest expiry.
Returns OverviewResponse JSON: symbol, spotPrice, timestamp, riskFreeRate, dividendYield, sentiment, gexSummary, maxPain[], expectedMoves[], termStructure[], ivSurface[], topFlow[].
Inputs: symbol (required), expiration.
Compact analytics snapshot for a symbol — a lighter-weight summary than the full overview, suitable for quick checks and cards.
Args: symbol: Underlying ticker. expiration: Unix timestamp of a specific expiry, or "all". Omit for the nearest expiry.
Returns the SnapshotResponse JSON as computed by the analytics engine.
Inputs: symbol (required), expiration.
Public GEX-by-strike heatmap for a watchlist symbol (no key needed, IP rate-limited, cached ~5 min). A lightweight, unauthenticated way to see gamma exposure per strike without a plan.
Args:
symbol: A watchlist ticker (SPY, QQQ, AAPL, NVDA, TSLA, …). Defaults to
SPY. Symbols outside the public watchlist return an error — use the
authenticated get_gex for arbitrary symbols.
expiry: Optional Unix expiration timestamp; omit for the nearest expiry.
Returns the heatmap JSON: symbol plus GEX by strike.
Inputs: expiry, symbol.
Service health check: returns {status, supabase, stripe}. Public — no key needed. Use to verify GREEKS_BASE_URL is reachable before other calls.
Inputs: no named parameters.
List the available commercial plans with prices, limits and included routes (Free / Trader / Pro / Institutional). Public — no key needed.
Use this to explain to the user which analytics their plan unlocks, or why a call returned 402/403.
Inputs: no named parameters.
Public options screener across the curated watchlist (~26 liquid names: SPY, QQQ, AAPL, NVDA, TSLA, …). Returns a per-symbol row with spot price, sentiment and headline analytics — the fastest way to DISCOVER which symbols are interesting before drilling in with the authenticated analytics tools.
Public — no key needed (IP rate-limited). Takes no arguments; the watchlist is fixed server-side.
Returns the screener JSON (rows[] of symbol/spotPrice/sentiment/…).
Inputs: no named parameters.
Public track record — aggregated accuracy of the published analytics over roughly the last 35 days (per-symbol daily snapshots vs realized high/low/ close). Use it to gauge how the signals have performed historically.
Public — no key needed. Takes no arguments.
Returns the track-record JSON as computed server-side (updatedAt + records).
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 12 tools
Most tools have clearly distinct purposes (greeks, GEX, flow, max pain, levels), but get_overview and get_snapshot both provide aggregated summaries and could be confused. Also get_gex and gex_heatmap overlap in concept, though one is authenticated and more comprehensive.
Most tools follow a verb_noun pattern (get_greeks, get_flow, list_plans), but a few use bare nouns or noun_noun (health, screener, gex_heatmap, track_record). This mixed convention is noticeable but not chaotic, so it remains readable.
With 12 tools, the server is well-scoped for an options analytics service. Each tool serves a clear purpose, from core analytics to public discovery and meta operations, without excessive overlap or unnecessary bloat.
The tool surface covers a comprehensive set of options analytics: greeks, GEX, flow, max pain, and levels, plus an aggregated overview. Minor gaps exist (e.g., no standalone expected-moves tool), but these are embedded in overview and snapshot, so agents can work around them.
Options analytics: 17 pricing models, 17 Greeks, GEX, IV, 23 screeners, unusual, dark pool, max pain
Real-time & historical options analytics: GEX, dealer positioning, vol, VRP, 0DTE, CME futures
Live US options chains with Greeks and IV, a screener, SQL, and FMP fundamentals.
Production MCP server for US equity and options intelligence: real-time IV radar, Monte Carlo simulation, options pressure, strategy backtesting, AI prediction, pre-trade risk analysis, and automated stock research reports.
