mcp-monte-carlo

Give any AI agent the power to run a serious Monte Carlo forecast for a stock or ETF — in one tool call.

This is an MCP (Model Context Protocol) server. Connect it once to Hermes, Claude Desktop, Cursor, or any MCP-capable agent, and the agent can download market history, fit a volatility model, simulate thousands of future price paths, and return percentiles, drawdowns, and risk probabilities — without you writing a single line of simulation code.

You:  "What does a bad year look like for SPY over the next 12 months?"
Agent → forecast_asset_monte_carlo("SPY")
      → EGARCH + skewed-t Monte Carlo (5,000 paths by default)
You ← JSON: price/return percentiles, vol, max drawdowns, loss probabilities

Why this matters

Large language models are excellent at reasoning and explanation. They are not engines for sampling fat-tailed returns under time-varying volatility. Left alone, an agent might invent plausible-looking percentiles or hand-wave “historical vol $\times\sqrt{T}$”.

This server closes that gap:

The agent stays in charge of interpretation and conversation. The MCP owns estimation and simulation.

Related MCP server: HowRisky MCP Server

What it does (pipeline)

Yahoo Finance (max history)
        │  adjusted daily Close
        ▼
  Log returns
        │
        ▼
  Fit EGARCH(1,1) + leverage  +  skewed-t shocks
        │  constant mean drift (historical mean)
        ▼
  Simulate N paths  (default 5,000) out to 10 years
        │
        ▼
  Summarize each horizon → percentiles, vol, MDD, probabilities

1. Data

Uses yfinance to pull the maximum available daily history. The Close field is already adjusted for splits and dividends, so returns are suitable for long-horizon compounding.

2. Returns and drift

Prices are converted to log returns:

r_t=\ln\left(\frac{P_t}{P_{t-1}}\right)

The mean model is constant: each simulated day has drift equal to the fitted historical average $\mu$. That is a simple, transparent assumption — not a crystal ball for future expected return.

3. Volatility: EGARCH with leverage

Equity volatility is neither constant nor symmetric:

• Volatility clustering — turbulent days tend to follow turbulent days.

• Leverage effect — large down moves tend to raise future vol more than equally large up moves.

This server fits EGARCH(1,1) with leverage ($p=1$, $o=1$, $q=1$) via the arch package. Conditionally, log-variance evolves roughly as:

\ln(\sigma_t^2)=\omega+\alpha\bigl(\lvert z_{t-1}\rvert-\mathbb{E}[\lvert z\rvert]\bigr)+\gamma z_{t-1}+\beta\ln(\sigma_{t-1}^2)

For equities, the leverage coefficient $\gamma$ is typically negative: a negative shock $z$ increases tomorrow’s volatility.

4. Shocks: skewed Student-t

Gaussian shocks understate crash risk. Standardized innovations are drawn from a skewed t distribution, so simulated paths can show:

• fat tails (extreme moves more often than a normal),

• skewness (asymmetric left/right risk).

5. Monte Carlo paths

Given the fitted parameters, the server simulates $N$ forward trajectories (n_paths; vectorized NumPy loop for stability out to multi-year horizons). Each path is a full price series; horizons are slices of those same paths so short- and long-term stats are coherent.

6. Horizons (trading days)

Tools

forecast_asset_monte_carlo(ticker, n_paths=5000)

When to use: The user wants forward scenarios, risk ranges, or path statistics for a ticker (e.g. SPY, AAPL).

For each horizon, the JSON includes:

• Price percentiles — 1, 5, 10, 25, 50, 75, 90, 95, 99

• Return percentiles (%) — same grid, vs today’s price

• Annualized volatility (%) — cross-sectional vol of path outcomes at that horizon

• Max-drawdown percentiles (%) — peak-to-trough loss along each path up to that horizon

• Probabilities — end below start, ±20% moves, max drawdown over 20%

n_paths defaults to 5000 (minimum 100). More paths → smoother percentile estimates, slower run.

inspect_asset_model(ticker)

When to use: Validate data quality or model sanity before (or instead of) a full forecast — enough history? sensible parameters? how fat are residual tails?

Returns history span, last price, fitted EGARCH + skew-t parameters, AIC/BIC, last conditional volatility (daily and annualized), and residual skewness / excess kurtosis.

Does not simulate paths. Prefer forecast_asset_monte_carlo for percentiles and drawdowns.

Requirements

• macOS, Linux, or Windows

• uv (recommended)

• Python ≥ 3.12 (declared in pyproject.toml)

• Network access (Yahoo Finance download)

Quick start (local)

cd /path/to/mcp-monte-carlo
uv sync

Smoke-test without MCP:

uv run python -c "
from server import run_inspect, run
import json
print(json.dumps(run_inspect('SPY'), indent=2))
print(json.dumps(run('SPY', 200)['horizons']['1y'], indent=2))
"

Run the MCP server on stdio:

uv run mcp-monte-carlo
# or, from a published clone / path:
uvx --from /path/to/mcp-monte-carlo mcp-monte-carlo

Connect an AI agent

Hermes Agent (~/.hermes/config.yaml)

Prefer uv run against a synced project (faster and more reliable than a cold uvx):

mcp_servers:
  mcp-monte-carlo:
    command: /opt/homebrew/bin/uv   # which uv  → paste absolute path
    args:
      - run
      - --directory
      - /ABSOLUTE/PATH/TO/mcp-monte-carlo
      - mcp-monte-carlo
    connect_timeout: 120
    timeout: 300

Then: hermes mcp test mcp-monte-carlo or /reload-mcp in a chat.

Cursor / Claude Desktop

{
  "mcpServers": {
    "mcp-monte-carlo": {
      "command": "uvx",
      "args": [
        "--from",
        "/ABSOLUTE/PATH/TO/mcp-monte-carlo",
        "mcp-monte-carlo"
      ]
    }
  }
}

Once published on GitHub, others can point --from at the repo URL or clone locally and use the same pattern.

Example agent prompts

• “Inspect the EGARCH model for QQQ, then forecast with 2,000 paths.”

• “For AAPL, what is the 5th percentile price in 1 year, and the probability of a >20% max drawdown?”

• “Compare 1-year median and 95th percentile max drawdown for SPY vs TLT.”

Project layout

mcp-monte-carlo/
├── server.py          # MCP tools + EGARCH/skew-t Monte Carlo (single module)
├── pyproject.toml     # package metadata, deps, console entry point
├── uv.lock            # locked dependency versions
├── README.md
└── .gitignore

One Python file keeps the project easy to read, audit, and ship.

Model caveats (read this)

This is a research / educational risk tool, not investment advice and not a guarantee of future prices.

• Past drift $\mu$ is not a forecast of expected return; long-horizon medians inherit that assumption.

• EGARCH(1,1)+leverage and skewed-t are strong defaults for many liquid equities/ETFs — not universally “optimal” for every ticker.

• Yahoo data quality and corporate actions can affect results; always check inspect_asset_model on unfamiliar symbols.

• Extremely long horizons (5y–10y) compound model risk; treat tails as illustrative, not certainties.

License / authorship

Created by Alexandre Martins. Use and adapt freely for personal agents and learning; if you redistribute, keep attribution and these caveats visible.