optionslab

<h1 align="center">optionslab</h1>

<p align="center"><em>Options analytics for traders and learners — a clean Python library, a friendly CLI, and a Model-Context-Protocol server, all in one package.</em></p>

<p align="center"> <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"></a> <a href="https://www.python.org/downloads/release/python-3120/"><img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12%2B-blue.svg"></a> <a href="https://github.com/pradhann/options-chain-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/pradhann/options-chain-mcp/actions/workflows/ci.yml/badge.svg"></a> <a href="https://modelcontextprotocol.io"><img alt="MCP compatible" src="https://img.shields.io/badge/MCP-compatible-7c3aed.svg"></a> <a href="https://github.com/astral-sh/ruff"><img alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"></a> <a href="https://pradhann.github.io/options-chain-mcp/"><img alt="Docs" src="https://img.shields.io/badge/docs-mkdocs--material-007ec6.svg"></a> </p>

<p align="center"> <a href="https://pradhann.github.io/options-chain-mcp/">Documentation</a> · <a href="USAGE.md">Quick reference</a> · <a href="https://github.com/pradhann/options-chain-mcp/issues">Report a bug</a> </p>

---

Why optionslab

• One model, three front doors — a typed Python library, a verb-per-task CLI, and an MCP server that any Claude client can talk to.
• The math you'd derive on paper — vectorized Black-Scholes price + Greeks (Δ, Γ, Θ, V, ρ, vanna, vomma, charm), put-call parity checker, synthetic-position verifier. Every analytic Greek matches the py_vollib reference to 1e-6.
• Position-first, not strategy-first — a Position is just a list of legs. Payoff, value, Greeks, scenario grids, and metrics (max P / max L / breakevens) are all the same Position queried different ways.
• Volatility as a market, not a number — RV estimator zoo (close-to-close, Parkinson, Garman-Klass, Rogers-Satchell, Yang-Zhang), VRP, VIX term structure + regime label, 25Δ Risk Reversal / Butterfly, model-free VIX strip, event-implied move.
• A daily Vol Dashboard — five computed fields, two-year percentiles, one ritual.
• Tested, typed, documented — 50 pytest cases pinning the math. Every result is a dataclass with .to_dict() for clean JSON at the MCP/CLI edge.

Install

pip install optionslab

Or, from source:

git clone https://github.com/pradhann/options-chain-mcp
cd options-chain-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Quick start — Python

from optionslab import Position, MarketContext
from optionslab.analysis import expiration_payoff, position_metrics, greeks

pos = Position.from_dicts([
    {"side": "long",  "option_type": "call", "strike": 100, "premium": 6.0},
    {"side": "short", "option_type": "call", "strike": 110, "premium": 2.5},
], name="bull-call-100-110")

expiration_payoff(pos, s_t=115).total_dollars   # 650.0
position_metrics(pos).breakevens                 # [103.5]

market = MarketContext.explicit(spot=105, r=0.045)
greeks(pos, market, ivs=0.30).delta_dollars      # ≈ $25 per +$1 in spot

Quick start — CLI

# Live options chain with per-strike Greeks
optionslab chain --ticker SPY --near-money 6

# Closed-form metrics for an inline position
optionslab metrics --legs '[{"side":"long","option_type":"call","strike":100,"premium":6},
                            {"side":"short","option_type":"call","strike":110,"premium":2.5}]'

# The classic 2×2 payoff primitives chart
optionslab chart --kind primitives --strike 100 --premium 5 --save-plot primitives.png

# The daily Vol Dashboard
optionslab dashboard --save-plot dashboard.png

See USAGE.md for the full one-page reference of every verb and chart kind.

Quick start — MCP (Claude Desktop / Claude Code)

optionslab ships an MCP server so any Claude client can call its 40+ tools — pulling chains, valuing positions, drawing charts as inline images.

Add to your Claude config:

{
  "mcpServers": {
    "optionslab": {
      "command": "python",
      "args": ["-m", "optionslab.mcp_server"]
    }
  }
}

Or, from a terminal Claude Code session:

claude mcp add optionslab -s user -- python -m optionslab.mcp_server

Restart Claude and ask things like "pull the SPY chain at the nearest monthly and chart the 25Δ skew" or "build a bull call spread on AAPL and show me the P&L grid for ±20% over 30 days."

Screenshots

<table> <tr> <td align="center" width="50%"><b>Payoff primitives — Day 3 curriculum chart</b><br>_{2×2 long/short × call/put, each annotated with breakeven and max P/L.}<br><br><img src="docs/assets/primitives.png" alt="Payoff primitives 2x2 grid"></td> <td align="center" width="50%"><b>Vol Dashboard — the daily ritual</b><br>_{Five fields with 2-year percentile bars: ATM IV, VRP, term ratio, 25Δ RR/BF.}<br><br><img src="docs/assets/dashboard.png" alt="Vol Dashboard panel"></td> </tr> <tr> <td align="center"><b>Delta sigmoid, with py_vollib oracle overlay</b><br>_{Verified against the standard reference at every sample.}<br><br><img src="docs/assets/delta.png" alt="Delta vs spot sigmoid"></td> <td align="center"><b>Position scenario grid</b><br>_{Dollar P&L over spot moves × days forward — heatmap of bull call spread, capped at $650 / floored at −$350.}<br><br><img src="docs/assets/scenario.png" alt="P&L scenario heatmap"></td> </tr> </table>

What's inside

Layer	Lives in	Purpose
Pricing	optionslab.pricing	Vectorized BS + all 8 Greeks + IV solver
Core types	optionslab.core	Leg, Position, MarketContext, typed *Result dataclasses
Data	optionslab.data	Quote, chain (with Greeks), events, vol fetchers
Analysis	optionslab.analysis	Payoff, valuation, metrics, scenario, parity, synthetics, vol/ (VRP, term, skew, strip, event, dashboard)
Plotting	optionslab.plotting	Returns Matplotlib Axes / Figure; never calls plt.show()
Adapters	optionslab.adapters	Thin CLI + MCP + interactive shells over the analysis layer
Storage	optionslab.storage	.optionslab/positions.json + percentile history files

Strict dependency direction: pricing ← core ← analysis ← plotting ← adapters. No cycles.

Documentation

Full docs are published at https://pradhann.github.io/options-chain-mcp/ (built with MkDocs Material from the docs/ tree).

For a single-page reference of every verb, tool, and chart kind, see USAGE.md.

Contributing

Issues and PRs welcome. To set up a dev environment:

git clone https://github.com/pradhann/options-chain-mcp
cd options-chain-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest                       # 50 tests, ~1 second

If you're fixing math, please add a test that pins the expected number. The repo's principle is "breaking the math should fail a test before it ships."

License

MIT © Nripesh Pradhan