greeks-mcp

greeks-mcp

A Model Context Protocol server that exposes theGreeks 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 livefrom the API.

Only derived/computed analytics are exposed — no raw market data isredistributed.

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

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 12 tools. uvdownloads and runs the published package on demand in an isolated environment, sothere's nothing to install or keep updated by hand.

Prefer pipx? pipx install greeks-mcp, then use "command": "greeks-mcp" with noargs.

Where the config block goes

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

Ready-to-copy configs live in examples/. After reloading, the servershows up under Cursor's Settings → MCP with a green dot and its 12 tools; type@greeks-analytics in chat (or just ask for GEX/greeks/max pain) to use them.

Tools

All analytics tools take symbol (required) and optional expiration (a Unixtimestamp, or "all" for every expiration; omit for the nearest expiry).get_greeks also accepts range="atm", moneyness="low,high" and limit.

Configuration

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 12 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, workflowpublish.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 andpushing 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 all12 tools, and publishes.

Notes

• Plans & errors: a 402/403 means your plan doesn't include that route (oryou hit the symbol/rate limit). Call list_plans to see what each tier unlocks.
• expiration="all" returns every expiration — richer but slower. For heavynames 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.