Metadata-Version: 2.4
Name: apexvol-mcp
Version: 0.1.0
Summary: MCP server for ApexVol options analytics - query options data via Claude Code or Claude Desktop
Project-URL: Homepage, https://apexvol.com
Project-URL: Documentation, https://apexvol.com/docs/api
Project-URL: Source, https://github.com/ryansilk/apexvol-mcp
Project-URL: Issues, https://github.com/ryansilk/apexvol-mcp/issues
Author-email: ApexVol <support@apexvol.com>
Maintainer-email: ApexVol <support@apexvol.com>
License: MIT
License-File: LICENSE
Keywords: analytics,claude,mcp,options,trading,volatility
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp<2.0,>=1.2.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# ApexVol MCP Server

A Model Context Protocol (MCP) server that provides natural language access to ApexVol's options analytics platform. Query options chains, volatility metrics, Greeks, flow analysis, and more using Claude Code or Claude Desktop.

## Architecture

```
Customer's Machine                     ApexVol Platform
┌─────────────────────┐               ┌─────────────────────┐
│ Claude Code/Desktop │               │ apexvol.com         │
│         │           │               │                     │
│         ▼           │               │                     │
│   ApexVol MCP       │──── HTTPS ───▶│  /api/mcp/data/...  │
│   (runs locally)    │               │                     │
└─────────────────────┘               └─────────────────────┘
```

The MCP server runs locally on your machine and makes API calls to the ApexVol platform. No additional infrastructure required.

## Features

- **43 Analytics Tools** — every `/api/mcp/data` endpoint is reachable from Claude
- **Natural Language Interface** - Ask questions like "What's the IV rank for SPY?"
- **Claude Code & Desktop Support** - Works with CLI and desktop applications
- **Token Authentication** - Secure API token validation
- **Built-in health check** - `apexvol-mcp --check` verifies your install and token

## Available Tools

### Options Chain (6 tools)
- `get_options_chain` - Full options chain for any ticker
- `get_expirations` - Available expiration dates
- `get_options_by_delta` - Find options at specific delta
- `get_stock_price` - Current price and company info
- `calculate_expected_move` - Expected move from straddle pricing
- `get_historical_chain` - Chain snapshot on any past trading day

### Volatility Analysis (7 tools)
- `get_iv_rank` - IV rank and percentile
- `get_volatility_cone` - IV vs historical realized volatility
- `get_volatility_risk_premium` - VRP (IV minus RV)
- `get_term_structure` - IV across expirations
- `find_iv_opportunities` - Mean reversion opportunities
- `get_vix_snapshot` - VIX level and term-structure state
- `get_monies_surface` - ORATS smoothed surface: implied, forecast, or model-vs-market comparison

### Greeks & GEX (5 tools)
- `get_gex` - Gamma Exposure by strike
- `get_charm_exposure` - Delta decay exposure
- `get_third_order_greeks` - Speed, zomma, color, vomma, ultima
- `get_greeks_heatmap` - Greeks across strikes and expirations
- `get_cross_index_gex` - Compare GEX across indices

### Options Flow (3 tools)
- `get_options_flow` - Flow and unusual activity ⚠️ *temporarily unavailable — upstream feed lacks reliable intraday volume; the tool says so instead of returning zeros*
- `get_smart_money_flow` - Institutional flow patterns ⚠️ *same limitation as above*
- `scan_volatility_arb` - Cross-index volatility arbitrage

### Strategy Building (5 tools)
- `build_strategy` - Build options strategies (iron condor, spreads, etc.)
- `analyze_strategy` - Full P&L and Greeks analysis
- `optimize_strategy` - Find optimal strikes
- `simulate_option_chain` - Black-Scholes what-if re-pricing (price/DTE/IV shift)
- `calculate_probability_of_profit` - PoP for any set of legs

### Risk Management (4 tools)
- `calculate_portfolio_greeks` - Aggregate portfolio Greeks
- `run_scenario_analysis` - What-if scenarios
- `generate_stress_tests` - Stress test results
- `get_hedge_recommendations` - Delta-hedge suggestions (stock + option legs)

Positions are passed as a JSON array (ticker, position_type, quantity, strike,
expiration, Greeks) — pull option Greeks from `get_options_chain` first. Plain
text ("AAPL 100 shares") works for stock-only portfolios.

### Events & Screening (5 tools)
- `get_earnings_calendar` - Upcoming earnings
- `analyze_earnings_history` - Historical earnings moves
- `screen_market` - Market screening (high IV, unusual volume, etc.)
- `get_market_overview` - Market-wide volatility overview
- `get_economic_calendar` - Macro events (CPI, FOMC, jobs...)

### Ticker Analytics (8 tools)
- `get_ticker_analytics` - One tool, eight views: `skew`, `dividends`,
  `borrow_rate`, `correlation`, `hv_regimes`, `price_context`,
  `relative_value`, `greeks_exposure`
- `get_earnings_move_analysis` - seven views: `mispricing`, `historical_moves`,
  `expected_vs_actual`, `verdict`, `seasonality`, `post_drift`, `iv_crush`
- `get_max_pain` - Max pain strike and loss profile
- `get_volume_profile` - Volume/OI by strike with OI-implied support/resistance
- `get_zero_dte` - 0DTE gamma, flip level, max pain, theta decay (SPY/QQQ/SPX…)
- `get_orats_cores` - Raw ORATS cores row (340+ fields) with field selection
- `search_tickers` - Resolve names to symbols / check coverage
- `scan_relative_value` - Market-wide IV/SPY mean-reversion and pairs scans

## Installation

### Prerequisites

- Python 3.10+
- An ApexVol Pro subscription and an API token (see "Getting a Token" below)

### Install the Package

We recommend [pipx](https://pipx.pypa.io) so the `apexvol-mcp` command is
isolated and always on your PATH:

```bash
pipx install apexvol-mcp
```

Plain `pip install apexvol-mcp` also works.

Or install from source:

```bash
cd apexvol-mcp
pip install -e .
```

### Verify the install

Before touching any Claude config, confirm the command works and your token
authenticates:

```bash
APEXVOL_API_TOKEN=avmcp_YOUR_TOKEN_HERE apexvol-mcp --check
```

`--check` prints the client version, auth result, and your remaining
rate-limit/monthly budget. If it says OK, the only step left is wiring it
into Claude.

## Configuration

### Claude Code (CLI)

One command:

```bash
claude mcp add apexvol -e APEXVOL_API_TOKEN=avmcp_YOUR_TOKEN_HERE -- apexvol-mcp
```

Or add to your project's `.mcp.json` or global `~/.claude.json` by hand:

```json
{
  "mcpServers": {
    "apexvol": {
      "command": "apexvol-mcp",
      "env": {
        "APEXVOL_API_TOKEN": "avmcp_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

### Claude Desktop App

**macOS**: Edit `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: Edit `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "apexvol": {
      "command": "apexvol-mcp",
      "env": {
        "APEXVOL_API_TOKEN": "avmcp_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `APEXVOL_API_TOKEN` | Yes | Your ApexVol API token |
| `APEXVOL_API_URL` | No | API URL (default: https://apexvol.com) |

## Usage

After configuration, restart Claude Code or Claude Desktop to load the MCP server.

### Example Queries

**Volatility Analysis:**
- "What's the IV rank for AAPL?"
- "Show me the volatility cone for SPY"
- "Is there a volatility risk premium in TSLA?"

**Options Chain:**
- "Get the options chain for QQQ expiring next week"
- "Find a 30 delta put on NVDA"
- "What's the expected move for AMZN earnings?"

**Greeks & GEX:**
- "What's the gamma exposure for SPY?"
- "Show me the GEX flip point for QQQ"
- "Compare GEX across major indices"

**Flow Analysis:**
- "What's the options flow in AAPL today?"
- "Any unusual options activity in META?"
- "Scan for volatility arbitrage opportunities"

**Strategy Building:**
- "Build an iron condor on SPY"
- "Analyze a 150/155 call spread on AAPL"
- "What are the Greeks for selling a 200 put on NVDA?"

**Risk Management:**
- "Calculate portfolio Greeks for 100 AAPL shares and 1 AAPL 200 call"
- "Run a stress test on my positions"
- "How should I hedge my delta exposure?"

**Market Overview:**
- "What's the market overview today?"
- "Show me stocks with high IV rank"
- "What earnings are coming up this week?"

## Response Format

All tools return structured data with a markdown summary:

```json
{
  "success": true,
  "data": { ... },
  "summary": "## AAPL IV Analysis\n\n| Metric | Value |\n...",
  "metadata": {
    "timestamp": "2025-01-08T10:30:00",
    "ticker": "AAPL"
  }
}
```

## Authentication

ApexVol MCP uses token-based authentication. Your token is sent with each API request to the ApexVol platform.

### Token Format
- Prefix: `avmcp_`
- Length: 38 characters total

### Getting a Token
API access requires an active **Pro** subscription:

1. Create and manage tokens at **apexvol.com/account → API Access** —
   issuance, rotation, and revocation are all self-service.
2. If the API Access tab isn't enabled on your Pro account yet (access is
   rolling out), email **support@apexvol.com** and we'll switch it on.

The token is sent with every request, so treat it like a password. If it
leaks, revoke it on the account page and create a new one.

## Troubleshooting

**Start with the health check** — it diagnoses most issues in one shot:

```bash
APEXVOL_API_TOKEN=avmcp_YOUR_TOKEN_HERE apexvol-mcp --check
```

### "Invalid or missing API token"
- Verify your `APEXVOL_API_TOKEN` environment variable is set correctly
- Ensure your token hasn't been revoked (check apexvol.com/account → API Access)
- Check that the token starts with `avmcp_`

### "Request timed out"
- Check your internet connection
- The ApexVol platform may be temporarily unavailable

### MCP Server Not Loading
- Restart Claude Code/Desktop after configuration changes
- Check that `apexvol-mcp` is in your PATH (`which apexvol-mcp`; pipx installs handle this automatically)
- Verify the configuration JSON syntax is valid

## Development

### Running Locally

```bash
# Install in development mode
pip install -e ".[dev]"

# Run the server directly
python -m apexvol_mcp.server
```

### Running Tests

```bash
pytest tests/
```

## Support

For issues or questions:
- Email: support@apexvol.com
- Documentation: https://apexvol.com/docs/api

## License

MIT — see the `license` field in `pyproject.toml`. The client wrapper is open
source; access to the ApexVol platform itself remains gated by your API token and
subscription.
