Quant Companion MCP

A Model Context Protocol (MCP) server that gives AI assistants real-time options analytics and trading strategy capabilities.

Why Use This

• No more Googling for option prices — just ask "what's AAPL 200 call worth?"
• Instant Greeks — delta, gamma, theta, vega calculated in real-time
• Backtesting in plain English — "backtest momentum strategy on SPY last 5 years"
• Volatility analysis — compare implied vs historical, spot overpriced options
• Monte Carlo simulations — "what's the probability NVDA hits $150 by March?"
• No coding required — just talk to Claude like you would a quant analyst

The AI can't hallucinate numbers. Every price, every Greek, every simulation comes from actual market data and deterministic math.

---

Example Prompts

Options Analysis

"What's the implied volatility on TSLA options right now vs its 30-day historical vol?"

"Price a 6-month AAPL 200 call with current market conditions"

"Show me the volatility smile for SPY options expiring next month"

"Is there any unusual options activity on NVDA today?"

Probability & Simulations

"What's the probability NVDA ends above $140 in 3 months?"

"Run a Monte Carlo simulation on AAPL for the next 6 months"

"Compare price forecasts using GBM vs local vol vs SABR models for META"

Strategy & Backtesting

"Backtest a 20/50 moving average crossover strategy on SPY from 2020 to now"

"Run the momentum_plus strategy on QQQ and show me the trades"

"Compare momentum_plus_multi against buy-and-hold SPY over 10 years"

"What would my returns be if I ran a dual momentum strategy on these ETFs?"

Risk Analysis

"Calculate Sharpe ratio, max drawdown, and VaR for this portfolio"

"How much would I have lost in the 2022 bear market with this strategy?"

"What's the worst-case scenario for holding TSLA calls through earnings?"

Quick Lookups

"What's AAPL trading at right now?"

"Get me SPY price history for the last 2 years"

"Show me all available option expirations for GOOGL"

---

Quick Start (5 minutes)

Prerequisites

• Node.js 18+ installed
• Claude Desktop app

Step 1: Clone and Build

git clone https://github.com/yourusername/quant-companion-mcp.git
cd quant-companion-mcp
npm install
npm run build

Step 2: Find Your Claude Config File

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Usually: C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

If the file doesn't exist, create it.

Step 3: Add the MCP Server

Open the config file and add this (replace the path with your actual path):

{
  "mcpServers": {
    "quant-companion": {
      "command": "node",
      "args": ["C:/full/path/to/quant-companion-mcp/packages/mcp-tools/dist/index.js"],
      "env": {
        "POLYGON_API_KEY": ""
      }
    }
  }
}

Important: Use the full absolute path. On Windows use forward slashes or escaped backslashes.

Step 4: Restart Claude Desktop

Completely quit Claude Desktop (not just close the window) and reopen it.

Step 5: Verify It Works

Open a new chat and ask:

What's AAPL trading at right now?

If you see a real price, you're good. If Claude says it can't access market data, check your path in the config.

---

Optional: Better Data with Polygon.io

Yahoo Finance works fine for most use cases but rate limits on options chains. For heavier usage:

1. Get a free API key at https://polygon.io
2. Add it to your config:

{
  "mcpServers": {
    "quant-companion": {
      "command": "node",
      "args": ["C:/path/to/packages/mcp-tools/dist/index.js"],
      "env": {
        "POLYGON_API_KEY": "your_key_here"
      }
    }
  }
}

The system automatically falls back to Yahoo if Polygon rate limits.

---

What You Can Do

Market Data

• get_current_price: Real-time stock/ETF price
• get_historical_prices: OHLCV data for any date range
• get_options_chain: Full options chain with strikes & expirations

Options Pricing

• price_option_black_scholes: European option pricing with all Greeks
• price_option_monte_carlo: MC pricing with confidence intervals
• compute_implied_vol: Back out IV from observed price

Volatility Analysis

• compute_historical_vol: Realized volatility from price history
• get_vol_smile: IV curve across strikes (single expiration)
• get_vol_surface: Full IV surface (strike × maturity)
• summarize_vol_regime: HV vs IV comparison with interpretation

Simulations & Forecasting

• simulate_price: GBM price simulation with probability analysis
• simulate_price_with_local_vol: Skew-adjusted simulation using vol surface
• compare_models_forecast_distribution: Compare GBM, Local Vol, SABR, Heston
• backtest_forecast_accuracy: Historical accuracy of forecast models

Risk & Strategy

• compute_risk_metrics: Sharpe, Sortino, max drawdown, VaR
• run_backtest: Strategy backtesting (MA crossover, momentum, mean reversion, dual momentum)
• detect_unusual_activity: Options flow analysis (volume spikes, sweeps)

---

Architecture

Claude / AI Assistant
        |
        | MCP Protocol (stdio)
        v
    mcp-tools
        - 18 MCP tool definitions
        - Market data providers (Yahoo Finance, Polygon.io)
        - Input validation (Zod schemas)
        |
        | Function calls
        v
    quant-core
        - Black-Scholes pricing & Greeks
        - Monte Carlo simulations
        - Implied volatility solver (Newton-Raphson)
        - Vol smile & surface computation
        - Risk metrics (Sharpe, Sortino, VaR, max drawdown)
        - Strategy backtesting framework
        - SABR & Heston stochastic vol models
        
        Pure functions. No side effects. No network calls.

---

Project Structure

packages/
  quant-core/           # Pure TypeScript math library
    blackScholes.ts     # BS pricing & Greeks
    monteCarlo.ts       # MC simulations
    impliedVol.ts       # Newton-Raphson IV solver
    volatility.ts       # Historical vol calculations
    volSmile.ts         # Smile curve computation
    volSurface.ts       # Surface interpolation
    risk.ts             # Sharpe, Sortino, VaR, drawdown
    backtest.ts         # Simple backtesting (MCP tools)
    sabr.ts             # SABR model calibration
    heston.ts           # Heston stochastic vol
    strategy/           # Advanced strategy framework

  mcp-tools/            # MCP server
    index.ts            # Server entry point (stdio transport)
    marketData.ts       # Yahoo/Polygon data providers
    tools/              # 18 MCP tool definitions

---

Development

# Run tests
npm test

# Build all packages
npm run build

# Dev mode (auto-rebuild)
npm run dev

---

Troubleshooting

Claude says it can't access the tools

• Make sure the path in config is absolute and correct
• Check that you ran npm run build
• Fully restart Claude Desktop (quit, not just close)

Getting rate limited

• Add a Polygon API key for better limits
• Space out rapid-fire options chain requests

Numbers look wrong

• Check if market is open (prices may be stale after hours)
• Options data can be delayed up to 15 min on free tier

Heston/SABR is slow

• First calibration takes 2-3 seconds, subsequent calls are faster
• This is expected for stochastic vol models

---

Known Issues

• Yahoo Finance rate limits aggressively on options chain calls, polygon fallback helps
• Heston calibration can be slow on first run (~2-3 sec)
• Vol surface interpolation gets weird at far OTM strikes

---

License

MIT