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*.

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.