Equity Monte Carlo Simulator

Dale a cualquier agente de IA el poder de ejecutar una previsión seria de Monte Carlo para una acción o ETF, en una sola llamada de herramienta.

GitHub

Prueba este MCPPatrocinado

Documentación

mcp-monte-carlo

Dale a cualquier agente de IA el poder de ejecutar un pronóstico Monte Carlo serio para una acción o ETF — en una sola llamada de herramienta.

Este es un servidor MCP (Model Context Protocol). Conéctalo una vez a Hermes, Claude Desktop, Cursor o cualquier agente compatible con MCP, y el agente podrá descargar el historial de mercado, ajustar un modelo de volatilidad, simular miles de trayectorias futuras de precios y devolver percentiles, drawdowns y probabilidades de riesgo — sin que escribas una sola línea de código de simulación.

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

Por qué esto importa

Los modelos de lenguaje grandes son excelentes para razonar y explicar. No son motores para muestrear retornos de colas pesadas bajo volatilidad variable en el tiempo. Si se les deja solos, un agente podría inventar percentiles que parecen plausibles o mencionar de forma vaga “vol histórica $\times\sqrt{T}$”.

Este servidor cierra esa brecha:

Sin este MCP	Con este MCP
El agente adivina rangos o cita números desactualizados	El agente llama a un pipeline estadístico reproducible
Sin tratamiento consistente de caídas / colas pesadas	Innovaciones t sesgadas modelan asimetría y colas pesadas
Supuestos de volatilidad constante ignoran agrupamiento	EGARCH captura volatilidad asimétrica impulsada por choques
Difícil comparar riesgo a 7 días vs. 10 años	Mismo modelo, mismas trayectorias, muchos horizontes en un solo JSON

El agente sigue a cargo de la interpretación y la conversación. El MCP posee la estimación y la simulación.

Qué hace (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. Datos

Usa yfinance para obtener el historial diario máximo disponible. El campo Close ya está ajustado por splits y dividendos, por lo que los retornos son adecuados para capitalización a largo plazo.

2. Retornos y deriva

Los precios se convierten en retornos logarítmicos:

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

El modelo de media es constante: cada día simulado tiene una deriva igual al promedio histórico ajustado $\mu$. Esa es una suposición simple y transparente — no una bola de cristal para el retorno esperado futuro.

3. Volatilidad: EGARCH con apalancamiento

La volatilidad de las acciones no es ni constante ni simétrica:

Agrupamiento de volatilidad — los días turbulentos tienden a seguir a días turbulentos.
Efecto apalancamiento — los movimientos a la baja grandes tienden a aumentar la volatilidad futura más que movimientos al alza igualmente grandes.

Este servidor ajusta EGARCH(1,1) con apalancamiento ($p=1$, $o=1$, $q=1$) mediante el paquete arch. Condicionalmente, la log-varianza evoluciona aproximadamente como:

\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)

Para acciones, el coeficiente de apalancamiento $\gamma$ suele ser negativo: un choque negativo $z$ aumenta la volatilidad de mañana.

4. Choques: t de Student sesgada

Los choques gaussianos subestiman el riesgo de caídas. Las innovaciones estandarizadas se extraen de una distribución t sesgada, por lo que las trayectorias simuladas pueden mostrar:

colas pesadas (movimientos extremos más frecuentes que en una normal),
asimetría (riesgo izquierdo/derecho asimétrico).

5. Trayectorias Monte Carlo

Dados los parámetros ajustados, el servidor simula $N$ trayectorias hacia adelante (n_paths; bucle NumPy vectorizado para estabilidad en horizontes de varios años). Cada trayectoria es una serie de precios completa; los horizontes son cortes de esas mismas trayectorias, de modo que las estadísticas a corto y largo plazo son coherentes.

6. Horizontes (días de negociación)

Etiqueta	Días de negociación	Calendario aproximado
`7d`	5	~1 semana
`30d`	21	~1 mes
`3m`	63	~3 meses
`6m`	126	~6 meses
`1y`	252	~1 año
`3y`	756	~3 años
`5y`	1260	~5 años
`10y`	2520	~10 años

Herramientas

`forecast_asset_monte_carlo(ticker, n_paths=5000)`

Cuándo usarla: El usuario quiere escenarios futuros, rangos de riesgo o estadísticas de trayectorias para un ticker (p. ej. SPY, AAPL).

Para cada horizonte, el JSON incluye:

Percentiles de precio — 1, 5, 10, 25, 50, 75, 90, 95, 99
Percentiles de retorno (%) — misma cuadrícula, vs. precio actual
Volatilidad anualizada (%) — vol transversal de los resultados de las trayectorias en ese horizonte
Percentiles de drawdown máximo (%) — pérdida de pico a valle a lo largo de cada trayectoria hasta ese horizonte
Probabilidades — terminar por debajo del inicio, movimientos de ±20%, drawdown máximo superior al 20%

n_paths por defecto es 5000 (mínimo 100). Más trayectorias → estimaciones de percentiles más suaves, ejecución más lenta.

`inspect_asset_model(ticker)`

Cuándo usarla: Validar la calidad de los datos o la cordura del modelo antes (o en lugar de) un pronóstico completo — ¿hay suficiente historial? ¿parámetros sensatos? ¿qué tan gruesas son las colas residuales?

Devuelve el rango del historial de retornos, el último precio, los parámetros ajustados de EGARCH + t sesgada, AIC/BIC, la última volatilidad condicional (diaria y anualizada), y la asimetría residual / exceso de curtosis.

No simula trayectorias. Prefiere forecast_asset_monte_carlo para percentiles y drawdowns.

Requisitos

macOS, Linux o Windows
uv (recomendado)
Python ≥ 3.12 (declarado en pyproject.toml)
Acceso a red (descarga de Yahoo Finance)

Inicio rápido (local)

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

Prueba de humo sin 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))
"

Ejecuta el servidor MCP en stdio:

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

Conectar un agente de IA

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

Prefiere uv run contra un proyecto sincronizado (más rápido y confiable que un uvx en frío):

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

Luego: hermes mcp test mcp-monte-carlo o /reload-mcp en un chat.

Cursor / Claude Desktop

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

Una vez publicado en GitHub, otros pueden apuntar --from a la URL del repositorio o clonarlo localmente y usar el mismo patrón.

Ejemplos de prompts para agentes

“Inspecciona el modelo EGARCH para QQQ, luego pronostica con 2,000 trayectorias.”
“Para AAPL, ¿cuál es el percentil 5 del precio en 1 año, y la probabilidad de un drawdown máximo >20%?”
“Compara el drawdown máximo mediano y el percentil 95 a 1 año para SPY vs TLT.”

Estructura del proyecto

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

Un solo archivo Python mantiene el proyecto fácil de leer, auditar y distribuir.

Advertencias del modelo (lee esto)

Esta es una herramienta de riesgo de investigación / educativa, no asesoría de inversión ni garantía de precios futuros.

La deriva pasada $\mu$ no es un pronóstico del retorno esperado; las medianas a largo plazo heredan esa suposición.
EGARCH(1,1)+apalancamiento y t sesgada son opciones predeterminadas sólidas para muchas acciones/ETFs líquidos — no universalmente “óptimas” para cada ticker.
La calidad de los datos de Yahoo y las acciones corporativas pueden afectar los resultados; siempre verifica inspect_asset_model en símbolos desconocidos.
Horizontes extremadamente largos (5–10 años) acumulan riesgo de modelo; trata las colas como ilustrativas, no como certezas.

Licencia / autoría

Creado por Alexandre Martins. Úsalo y adáptalo libremente para agentes personales y aprendizaje; si lo redistribuyes, mantén la atribución y estas advertencias visibles.