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