Quant Companion

Quant Companion MCP is a server that connects Claude-based assistants to real-time options analytics, pricing, risk metrics, backtesting, and Monte Carlo simulations. It enables you to ask natural-language questions and receive deterministic, data-driven results without coding, using real market data and established math.

How to use

You interact with the MCP using a client that speaks the MCP protocol. Start Claude Desktop, ensure the MCP server is running, and then ask for real-time prices, option Greeks, volatility analyses, or backtests. You can request market data like current prices, historical prices, and options chains, or perform pricing with Black–Scholes and Monte Carlo methods. You can run strategy backtests, volatility comparisons, and risk analyses all through natural-language prompts.

Typical usage patterns include asking for current prices (e.g., a stock’s real-time price), requesting an option price with Greeks, running a Monte Carlo scenario, backtesting a moving-average strategy, or comparing forecast models. The system uses real data and deterministic mathematical models, so results should be consistent and explainable.

How to install

Prerequisites you need before starting: node.js 18+ installed on your machine and Claude Desktop installed.

Step 1: Clone the project repository and build the MCP server.

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

Step 2: Find the Claude config file on your system. Use the path that matches your operating system. If the file does not exist, create it.

Windows example path: %APPDATA%\Claude\claude_desktop_config.json (usually C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json)

macOS example path: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux example path: ~/.config/Claude/claude_desktop_config.json

Step 3: Add the MCP server configuration to your Claude config. Use the absolute path to the built MCP tool index file.

{
  "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, you may use forward slashes or escaped backslashes.

Step 4: Completely quit Claude Desktop (not just close the window) and reopen it to apply the new MCP server configuration.

Step 5: Verify the server is working by asking for a real-time price in a new chat. For example, ask for AAPL’s price right now and confirm you receive a live quote.

Configuration and data options

Optional: Enable richer data access with Polygon.io by providing an API key. This increases rate limits for options data. If you have a Polygon API key, place it in the config as shown.

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

The system will fall back to Yahoo Finance data if Polygon rate limits are reached.

What you can do with Quant Companion MCP

Market Data: get_current_price, get_historical_prices, get_options_chain.

Options Pricing: price_option_black_scholes, price_option_monte_carlo, compute_implied_vol.

Volatility Analysis: compute_historical_vol, get_vol_smile, get_vol_surface, summarize_vol_regime.

Simulations & Forecasting: simulate_price, simulate_price_with_local_vol, compare_models_forecast_distribution, backtest_forecast_accuracy.

Risk & Strategy: compute_risk_metrics, run_backtest, detect_unusual_activity.

Architecture overview

Claude / AI Assistant communicates via MCP Protocol (stdio) to the mcp-tools backend, which provides a suite of 18 MCP tool definitions and multiple market data providers. The core math and analytics live in a pure functional library, with Black–Scholes pricing, Monte Carlo simulations, IV/volatility calculations, and risk/strategy tooling.

Development

Run tests and build locally to contribute or customize further.

# Run tests
npm test

# Build all packages
npm run build

# Dev mode with auto-rebuild
npm run dev

Troubleshooting

Claude says it can't access the tools

• Ensure the config path is absolute and correct
• Ensure you built the MCP tools
• Fully restart Claude Desktop (quit completely) and reopen it Getting rate limited
• Add a Polygon API key for higher limits
• Space out rapid-fire options chain requests Numbers look wrong
• Check if the market is open; prices may be stale after hours
• Options data can be delayed on free tiers Models like Heston/SABR may be slow on first use
• The initial calibration can take a couple of seconds; subsequent calls are faster

Notes

Known issues include Yahoo Finance rate limits for options chains, potential slowness on first Heston calibration, and interpolation quirks at far out-of-the-money strikes.

License

MIT

Available tools

get_current_price

Fetches the real-time price for stocks or ETFs.

get_historical_prices

Retrieves OHLCV data for a specified date range.

get_options_chain

Returns the full options chain with strikes and expirations.

price_option_black_scholes

Prices European options using the Black-Scholes model and provides Greeks.

price_option_monte_carlo

Prices options using Monte Carlo simulations with confidence intervals.

compute_implied_vol

Backs out implied volatility from an observed option price.

compute_historical_vol

Calculates realized volatility from price history.

get_vol_smile

Generates the implied vol curve across strikes for a single expiration.

get_vol_surface

Builds a full IV surface across strikes and maturities.

summarize_vol_regime

Interprets HV vs IV regimes and provides actionable takeaways.

simulate_price

GBM price simulations with probability analysis.

simulate_price_with_local_vol

Skew-adjusted simulations using a vol surface.

compare_models_forecast_distribution

Compares forecast distributions across models (GBM, Local Vol, SABR, Heston).

backtest_forecast_accuracy

Evaluates historical accuracy of forecast models.

compute_risk_metrics

Calculates Sharpe, Sortino, max drawdown, and VaR.

run_backtest

Backtests of strategies like MA crossover, momentum, mean reversion, or dual momentum.

detect_unusual_activity

Analyzes options flow for unusual activity signals.