Quant Companion MCP

# 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 ```bash 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): ```json { "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: ```json { "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 ```bash # 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