ArtBreguez/greeks-mcp

PyPI Python License: MIT Glama

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.

Quickstart

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.

Docker

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-mcp

The 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"].

Where the config block goes

The same mcpServers block works in every MCP client — only the file location differs.

Client	Config file
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Cursor (global)	~/.cursor/mcp.json
Cursor (per-project)	<project>/.cursor/mcp.json

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.

Tools

Tool	Endpoint	Min plan	What it returns
get_max_pain	/api/analytics/maxpain	Free	Max Pain strike per expiration
get_greeks	/api/analytics/greeks	Trader	Δ Γ Θ V ρ, theo price, mispricing per contract
get_gex	/api/analytics/gex	Trader	GEX/DEX per strike, total Net GEX, Gamma Flip
get_flow	/api/analytics/flow	Trader	Unusual-activity signals
get_vol_structure	/api/analytics/vol-structure	Trader	IV skew + term structure with plain-English reads
get_overview	/api/analytics/overview	Pro	Full dashboard (sentiment, GEX, max pain, expected move, IV surface, term structure, top flow)
get_vex	/api/analytics/vex	Pro	Vanna & Charm exposure (2nd-order dealer Greeks)
get_zero_dte	/api/analytics/zero-dte	Pro	0DTE focus panel — pin risk, gamma flip, max pain
get_gex_intraday	/api/analytics/gex-intraday	Pro	Intraday gamma-regime time-series + flip timing
get_track_record_detail	/api/analytics/track-record	Pro	Day-by-day level outcomes (the receipts behind the %)
get_snapshot	/api/analytics/snapshot	—	Compact analytics snapshot
get_levels	/api/analytics/levels	—	Options-derived support/resistance levels
screener	/api/public/screener	public	Watchlist screener — discover interesting symbols
gex_heatmap	/api/public/gex-heatmap	public	GEX-by-strike heatmap for a watchlist symbol
track_record	/api/public/track-record	public	Aggregated signal accuracy (~last 35 days)
list_plans	/api/billing/plans	public	Plans, prices, limits, routes
health	/health	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.

Configuration

Env var	Required	Default	Description
GREEKS_API_KEY	for /api/analytics/*	—	Your grk_... key. Public tools work without it.
GREEKS_BASE_URL	no	https://api.greeks.pro	API base URL
GREEKS_TIMEOUT	no	30	Per-request timeout (s)
MCP_TRANSPORT	no	stdio	stdio (for clients) or http

Run from source

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

Development

# 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 tools

Releasing (maintainers)

Published to PyPI via Trusted Publishing (OIDC — no API token stored). One-time setup:

1. On PyPI → Account settings → Publishing → add a pending publisher: project greeks-mcp, owner ArtBreguez, repo greeks-mcp, workflow publish.yml, environment pypi.
2. 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.0

The workflow builds the sdist+wheel, verifies the wheel installs and registers all 17 tools, and publishes.

Notes

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

License

MIT — see LICENSE.