Equity Monte Carlo Simulator

Dê a qualquer agente de IA o poder de executar uma previsão séria de Monte Carlo para uma ação ou ETF - em uma única chamada de ferramenta.

GitHub
1
Experimente este MCPPatrocinado

Documentação

mcp-monte-carlo

Dê a qualquer agente de IA o poder de executar uma previsão séria de Monte Carlo para uma ação ou ETF — em uma única chamada de ferramenta.

Este é um servidor MCP (Model Context Protocol). Conecte-o uma vez ao Hermes, Claude Desktop, Cursor ou qualquer agente compatível com MCP, e o agente poderá baixar o histórico de mercado, ajustar um modelo de volatilidade, simular milhares de caminhos futuros de preços e retornar percentis, drawdowns e probabilidades de risco — sem que você escreva uma única linha de código de simulação.

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 que isso importa

Modelos de linguagem grandes são excelentes em raciocínio e explicação. Eles não são motores para amostrar retornos de caudas pesadas sob volatilidade variável no tempo. Deixado sozinho, um agente pode inventar percentis aparentemente plausíveis ou usar uma aproximação genérica de “vol histórica $\times\sqrt{T}$”.

Este servidor preenche essa lacuna:

Sem este MCPCom este MCP
O agente adivinha faixas ou cita números desatualizadosO agente chama um pipeline estatístico reproduzível
Sem tratamento consistente de crashes / caudas pesadasInovações t assimétricas modelam assimetria e caudas pesadas
Suposições de volatilidade constante ignoram agrupamentoEGARCH captura volatilidade assimétrica impulsionada por choques
Difícil comparar risco de 7 dias vs. 10 anosMesmo modelo, mesmos caminhos, vários horizontes em um único JSON

O agente permanece responsável pela interpretação e conversa. O MCP é responsável pela estimação e simulação.

O que ele faz (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. Dados

Usa yfinance para obter o histórico diário máximo disponível. O campo Close já está ajustado para splits e dividendos, então os retornos são adequados para capitalização de longo prazo.

2. Retornos e drift

Os preços são convertidos em retornos logarítmicos:

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

O modelo de média é constante: cada dia simulado tem drift igual à média histórica ajustada $\mu$. Essa é uma suposição simples e transparente — não é uma bola de cristal para o retorno esperado futuro.

3. Volatilidade: EGARCH com alavancagem

A volatilidade de ações não é nem constante nem simétrica:

  • Agrupamento de volatilidade — dias turbulentos tendem a seguir dias turbulentos.
  • Efeito de alavancagem — grandes movimentos para baixo tendem a aumentar a volatilidade futura mais do que movimentos para cima igualmente grandes.

Este servidor ajusta EGARCH(1,1) com alavancagem ($p=1$, $o=1$, $q=1$) via pacote arch. Condicionalmente, a log-variância evolui 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 ações, o coeficiente de alavancagem $\gamma$ é tipicamente negativo: um choque negativo $z$ aumenta a volatilidade de amanhã.

4. Choques: t de Student assimétrica

Choques gaussianos subestimam o risco de crash. Inovações padronizadas são extraídas de uma distribuição t assimétrica, então os caminhos simulados podem mostrar:

  • caudas pesadas (movimentos extremos mais frequentes que o normal),
  • assimetria (risco assimétrico à esquerda/direita).

5. Caminhos de Monte Carlo

Dados os parâmetros ajustados, o servidor simula $N$ trajetórias futuras (n_paths; loop NumPy vetorizado para estabilidade em horizontes de vários anos). Cada caminho é uma série de preços completa; os horizontes são fatias desses mesmos caminhos, para que estatísticas de curto e longo prazo sejam coerentes.

6. Horizontes (dias de negociação)

RótuloDias de negociaçãoCalendário aproximado
7d5~1 semana
30d21~1 mês
3m63~3 meses
6m126~6 meses
1y252~1 ano
3y756~3 anos
5y1260~5 anos
10y2520~10 anos

Ferramentas

forecast_asset_monte_carlo(ticker, n_paths=5000)

Quando usar: O usuário quer cenários futuros, faixas de risco ou estatísticas de caminho para um ticker (ex.: SPY, AAPL).

Para cada horizonte, o JSON inclui:

  • Percentis de preço — 1, 5, 10, 25, 50, 75, 90, 95, 99
  • Percentis de retorno (%) — mesma grade, vs. preço atual
  • Volatilidade anualizada (%) — vol transversal dos resultados do caminho naquele horizonte
  • Percentis de drawdown máximo (%) — perda pico-a-vale ao longo de cada caminho até aquele horizonte
  • Probabilidades — terminar abaixo do início, movimentos de ±20%, drawdown máximo acima de 20%

n_paths padrão é 5000 (mínimo 100). Mais caminhos → estimativas de percentil mais suaves, execução mais lenta.

inspect_asset_model(ticker)

Quando usar: Validar qualidade dos dados ou sanidade do modelo antes (ou em vez de) uma previsão completa — histórico suficiente? parâmetros sensatos? quão pesadas são as caudas dos resíduos?

Retorna o período do histórico, último preço, parâmetros ajustados de EGARCH + t assimétrica, AIC/BIC, última volatilidade condicional (diária e anualizada) e assimetria / curtose excessiva dos resíduos.

Não simula caminhos. Prefira forecast_asset_monte_carlo para percentis e drawdowns.

Requisitos

  • macOS, Linux ou Windows
  • uv (recomendado)
  • Python ≥ 3.12 (declarado em pyproject.toml)
  • Acesso à rede (download do Yahoo Finance)

Início rápido (local)

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

Teste rápido sem 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))
"

Execute o servidor MCP em stdio:

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

Conecte um agente de IA

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

Prefira uv run contra um projeto sincronizado (mais rápido e confiável do que um uvx a frio):

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

Depois: hermes mcp test mcp-monte-carlo ou /reload-mcp em um chat.

Cursor / Claude Desktop

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

Uma vez publicado no GitHub, outros podem apontar --from para a URL do repositório ou clonar localmente e usar o mesmo padrão.

Exemplos de prompts para agentes

  • “Inspecione o modelo EGARCH para QQQ, depois faça a previsão com 2.000 caminhos.”
  • “Para AAPL, qual é o preço no 5º percentil em 1 ano, e a probabilidade de um drawdown máximo >20%?”
  • “Compare o drawdown máximo mediano e o do 95º percentil em 1 ano para SPY vs TLT.”

Estrutura do projeto

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

Um único arquivo Python mantém o projeto fácil de ler, auditar e distribuir.

Ressalvas do modelo (leia isto)

Esta é uma ferramenta de risco educacional / de pesquisa, não é aconselhamento de investimento e não é garantia de preços futuros.

  • O drift passado $\mu$ não é uma previsão de retorno esperado; medianas de longo prazo herdam essa suposição.
  • EGARCH(1,1)+alavancagem e t assimétrica são padrões fortes para muitas ações/ETFs líquidos — não universalmente “ótimos” para cada ticker.
  • A qualidade dos dados do Yahoo e ações corporativas podem afetar os resultados; sempre verifique inspect_asset_model em símbolos desconhecidos.
  • Horizontes extremamente longos (5–10 anos) amplificam o risco do modelo; trate as caudas como ilustrativas, não como certezas.

Licença / autoria

Criado por Alexandre Martins. Use e adapte livremente para agentes pessoais e aprendizado; se redistribuir, mantenha a atribuição e estas ressalvas visíveis.