CryptoScholar

Servidor MCP de análise técnica de criptomoedas ao vivo — EMA, RSI, MACD, ATR, Bandas de Bollinger, pontuação TSS e debate touro/urso com Claude AI via API gratuita da CoinGecko

GitHub

Experimente este MCPPatrocinado

Documentação

CryptoScholar

Análise técnica de criptomoedas, diretamente dentro do Claude. CryptoScholar é um servidor Model Context Protocol (MCP) que dá ao Claude capacidades de TA em tempo real — sem alternar gráficos, sem copiar e colar dados, sem perda de contexto.

Pergunte ao Claude "A SOL está preparada para um trade de swing?" e ele busca dados ao vivo da Binance, executa uma suíte completa de indicadores, pontua e entrega um debate fundamentado de alta/baixa — tudo em uma única resposta.

O que ele faz

O CryptoScholar expõe 15 ferramentas MCP que o Claude pode chamar nativamente:

`analyze_coin`

Análise técnica completa para qualquer moeda. Busca 300 dias de candles OHLCV reais da Binance (com fallback para CoinGecko) e calcula:

Indicador	Detalhes
Tendência	Alinhamento EMA-20, EMA-50, EMA-200 + inclinação semanal da EMA
Momentum	RSI-14, MACD (linha / sinal / histograma), ADX-14
Volatilidade	ATR-14, largura das Bandas de Bollinger, Volatilidade Histórica (20 dias anualizados)
Força Relativa	Moeda vs BTC (mudança da razão em 20 dias)
Múltiplos timeframes	Alinhamento EMA 4H — bônus/penalidade de ±3 TSS com base na EMA-20 vs EMA-50 de 4H
Divergência RSI	Altista / baixista / nenhuma — preço vs extremos do RSI nas últimas 30 barras
Tendência OBV	Direção do On-Balance Volume (subindo / caindo / estável) — bônus de confirmação de ±2 TSS
Taxa de Funding	Taxa de funding atual do perpétuo USDT-M — extremos positivos = longs excessivamente alavancados
Regime	Baixa / média / alta volatilidade — classificado por GaussianHMM de 3 estados (com fallback baseado em regras)
TSS	Trend Strength Score — composto de 0–100 (40% tendência + 30% momentum + 30% RS ± MTF ± OBV)

`rank_coins`

Passe uma lista de símbolos e receba-os classificados por TSS. Executa em paralelo (até 8 workers) para resultados rápidos em listas grandes. Cada resultado inclui TSS, regime, alinhamento EMA, alinhamento MTF 4H, divergência RSI, tendência OBV, taxa de funding, RSI-14, ADX-14 e RS vs BTC.

`top_coins`

Nenhuma lista de símbolos necessária. Busca as 50 principais moedas por capitalização de mercado no CoinGecko e as retorna classificadas por TSS. A filtragem inteligente remove automaticamente:

Stablecoins (USDT, USDC, DAI, etc.)
Tokens wrapped / sintéticos (WBTC, WETH, stETH, cbBTC, etc.)
Moedas de baixa liquidez com volume diário < US$ 10M

`correlate_coins`

Calcula a correlação de Pearson pareada dos retornos diários de 30 dias entre 2–20 moedas. Retorna a matriz de correlação completa, clusters de alta correlação (>0,85) e pares não correlacionados (<0,30) — útil para análise de diversificação de portfólio.

`market_context`

Sinais macro de mercado para contextualizar a análise individual de moedas. Usa dados globais do CoinGecko, oferta de stablecoins do DefiLlama e o Índice de Medo e Ganância do Alternative.me. Retorna:

Sinal	Descrição
Dominância BTC	% atual e mudança em 30 dias — caindo = capital rotacionando para alts
Razão ETH/BTC	Tendência de 20 dias — subindo = rali se ampliando
TOTAL3	Capitalização de mercado de altcoins (ex-BTC, ex-ETH) mudança em 30 dias
Oferta de stablecoins	Capitalização total de stablecoins e tendência de 30 dias (subindo = mais poder de compra)
Medo e Ganância	Índice do Alternative.me (0–100) — medo/ganância extremos aplicam modificador de ±5 ao MRS
ARS	Altcoin Rotation Score 0–100 — quão favorável o macro está para alts
MRS	Market Readiness Score 0–100 — prontidão geral do mercado para movimentos de alta

`debate`

O Claude lê os dados de TA ao vivo e gera um debate estruturado de alta/baixa fundamentado em valores reais de indicadores — não em opinião alucinada. Retorna:

Caso de alta — o que os técnicos dizem a favor
Caso de baixa — o que pode dar errado
Conclusão — síntese em uma frase

Ferramentas de watchlist

Listas persistentes de moedas armazenadas em SQLite (~/.cryptoscholar/watchlist.db).

Ferramenta	O que faz
`watchlist_add`	Adiciona símbolos a uma lista nomeada (cria a lista se necessário)
`watchlist_remove`	Remove símbolos; também limpa seus alertas
`watchlist_show`	Mostra todos os símbolos + alertas configurados de uma lista
`watchlist_lists`	Lista todas as watchlists nomeadas com contagens de símbolos
`watchlist_scan`	Executa uma análise TSS completa em cada moeda da lista — visão digest paralela
`alert_set`	Define um alerta de `tss_above`, `tss_below` ou `regime_change` em qualquer símbolo
`alert_check`	Busca TA ao vivo para todos os símbolos com alertas, reporta quais alertas dispararam, atualiza a linha de base

`train_regime_model`

Dispara manualmente um retreinamento do modelo HMM de regime de volatilidade com histórico de preços BTC recente. O modelo se retreina automaticamente a cada 7 dias — use isto após uma grande mudança na estrutura de mercado para forçar uma atualização imediata. Aceita uma flag opcional force=True para ignorar o cooldown de 7 dias.

`generate_report`

Gera um relatório de análise estruturado para uma ou mais moedas. Usa um pipeline de 3 estágios:

Cluster — agrupa sinais de TA em seções temáticas (tendência, momentum, volume/on-chain, volatilidade, força relativa)
Escrever — o Claude escreve um parágrafo narrativo para cada seção com base nos sinais agrupados
Montar — combina as seções em um relatório markdown formatado com uma tabela de estatísticas-chave no topo

Suporta análises aprofundadas de moeda única e relatórios de comparação multi-moeda (ex.: ["BTC", "ETH", "SOL"]). Passe output_format="json" para saída estruturada em vez de markdown. Até 10 símbolos por chamada.

Nenhuma chave de API necessária para dados de mercado. ANTHROPIC_API_KEY é necessária para as ferramentas debate e generate_report.

Novidades na v0.7.0

Ferramenta generate_report (ferramenta #15) — pipeline de 3 estágios Cluster → Escrever → Montar que produz um relatório markdown formatado para qualquer moeda ou lista de moedas. O Estágio 1 agrupa sinais de TA em clusters temáticos; o Estágio 2 usa o Claude para escrever seções narrativas; o Estágio 3 monta um relatório com uma tabela de estatísticas-chave.
Comparação multi-moeda — passe até 10 símbolos e receba um relatório comparativo com resumos por moeda, uma chamada de setup mais forte/mais fraco e um resumo comparativo geral.
Opção de saída JSON — passe output_format="json" para receber o dicionário completo do relatório estruturado em vez de markdown, útil para processamento downstream.
Análise paralela — dados de moedas para relatórios multi-símbolo são buscados em paralelo (até 8 workers) antes do estágio de escrita do Claude.

Início rápido

Requisitos: Python 3.11+

git clone https://github.com/cryptographer11/cryptoscholar.git
cd cryptoscholar
make install
cp .env.example .env
# Add your ANTHROPIC_API_KEY to .env (only needed for debate tool)
cryptoscholar

Adicionar ao Claude Code

Em ~/.claude/.mcp.json:

{
  "mcpServers": {
    "cryptoscholar": {
      "command": "python",
      "args": ["-m", "cryptoscholar"],
      "env": {
        "ANTHROPIC_API_KEY": "your_key_here"
      }
    }
  }
}

Reinicie o Claude Code. Agora você pode perguntar:

"Analise BTC para mim"
"Classifique ETH, SOL, AVAX e LINK por força de tendência"
"Mostre-me as 50 principais moedas classificadas por força de tendência"
"Como está o mercado macro agora?"
"Dê-me o caso de alta e baixa para DOGE com base na TA atual"
"Quão correlacionados estão BTC, ETH, SOL e AVAX no último mês?"
"Adicione BTC, ETH e SOL à minha watchlist principal"
"Defina um alerta em BTC se o TSS cair abaixo de 35"
"Verifique meus alertas"
"Dê-me o digest da minha watchlist principal"

Capturas de tela

Classificando BTC, ETH e XRP por Trend Strength Score — depois aprofundando no caso de baixa para XRP

rank_coins pontua cada moeda em tendência, momentum e força relativa vs BTC e as retorna ordenadas por TSS. Aqui BTC lidera com 63,7, ETH com 53,0 e XRP fica para trás com 47,8 — todas em regime low_vol. Pedir o caso de baixa do XRP imediatamente depois revela as razões técnicas específicas: inclinação semanal da EMA mais acentuada, MACD enfraquecendo e underperformance do ETH vs BTC sinalizada como pressão inicial de saída institucional.

Snapshot completo de análise técnica para SOL — indicadores, pontuação e caso de baixa em uma resposta

analyze_coin retorna um detalhamento estruturado cobrindo alinhamento da pilha EMA, RSI, MACD, ADX, ATR, largura das Bandas de Bollinger, tendência OBV, taxa de funding e força relativa vs BTC — tudo calculado a partir de 300 dias de candles ao vivo da Binance. O Claude então lê os valores brutos dos indicadores para gerar um caso de baixa fundamentado: resistência da EMA-200, inclinação semanal se acentuando e risco de cruzamento de baixa do MACD. Sem alternar gráficos, sem copiar e colar — o contexto completo de TA já está na janela do Claude.

Exemplo de saída

market_context()

{
  "btc_price_30d_change_pct": -8.4,
  "btc_dominance_current": 54.2,
  "btc_dominance_30d_change_pct": 2.1,
  "eth_btc_20d_change_pct": -5.3,
  "total3_30d_change_pct": -14.6,
  "stablecoin_supply_usd": 196500000000,
  "stablecoin_30d_change_pct": 2.8,
  "fear_greed_value": 22,
  "fear_greed_label": "Fear",
  "btc_trend_score": 35.0,
  "ars": 28.5,
  "stablecoin_score": 60.0,
  "fear_greed_modifier": 0.0,
  "mrs": 42.3
}

analyze_coin("SOL")

{
  "symbol": "SOL",
  "data_source": "binance",
  "price": 142.30,
  "tss": 79.2,
  "regime": "mid_vol",
  "regime_source": "hmm",
  "vrs": 55,
  "ema_alignment": "full_bull",
  "mtf_alignment_4h": "bullish",
  "rsi_divergence": "none",
  "obv_trend": "rising",
  "funding_rate": 0.00012,
  "indicators": {
    "rsi_14": 61.4,
    "macd_hist": 0.42,
    "adx_14": 28.1,
    "atr_14": 6.82,
    "hv_20": 68.4,
    "rs_btc": 4.2,
    "bb_width": 0.18,
    "rsi_divergence": "none",
    "obv_trend": "rising"
  }
}

correlate_coins(["BTC", "ETH", "SOL", "BNB"])

{
  "symbols": ["BTC", "ETH", "SOL", "BNB"],
  "lookback_days": 30,
  "matrix": {
    "BTC": {"BTC": 1.0, "ETH": 0.91, "SOL": 0.78, "BNB": 0.83},
    "ETH": {"BTC": 0.91, "ETH": 1.0, "SOL": 0.82, "BNB": 0.79},
    "SOL": {"BTC": 0.78, "ETH": 0.82, "SOL": 1.0, "BNB": 0.71},
    "BNB": {"BTC": 0.83, "ETH": 0.79, "SOL": 0.71, "BNB": 1.0}
  },
  "high_correlation_pairs": [
    {"symbol_a": "BTC", "symbol_b": "ETH", "correlation": 0.91}
  ],
  "uncorrelated_pairs": []
}

debate("SOL")

{
  "bull_case": "SOL is in a full bullish EMA stack with RSI at 61 — healthy momentum without overbought conditions. ADX at 28 confirms trending structure, and relative strength vs BTC is positive at +4.2%, signalling capital rotation into SOL. Rising OBV confirms volume is flowing in on up-days.",
  "bear_case": "Historical volatility at 68% is elevated, and Bollinger Band width is widening — conditions that often precede sharp reversals. A break below EMA-20 would invalidate the current trend structure. Funding rate at 0.012% hints at building long leverage.",
  "bottom_line": "Technicals are constructive for continuation but volatility is high; position sizing should reflect the risk."
}

Configuração

Variável	Padrão	Descrição
`ANTHROPIC_API_KEY`	—	Necessária para a ferramenta `debate`
`CRYPTOSCHOLAR_MODEL`	`claude-haiku-4-5-20251001`	Modelo Claude usado para debates (troque por Sonnet/Opus para análise mais profunda)
`CRYPTOSCHOLAR_LOG_DIR`	`/tmp`	Diretório para arquivos de log rotativos
`CRYPTOSCHOLAR_DATA_DIR`	`~/.cryptoscholar`	Diretório para o banco SQLite da watchlist

Moedas suportadas

O CryptoScholar funciona com qualquer moeda listada no CoinGecko ou Binance — basta passar o símbolo do ticker. Nenhuma configuração necessária.

Um mapa de símbolos integrado cobre 65 moedas principais para resolução instantânea — o universo completo das 50 principais por capitalização de mercado, incluindo BTC, ETH, SOL, BNB, XRP, ADA, AVAX, DOGE, LINK, DOT, SUI, TIA, WIF, BONK e mais. Para qualquer coisa fora dessa lista, o CryptoScholar consulta automaticamente a API de busca do CoinGecko para resolver o símbolo e usa fallback para OHLCV do CoinGecko se a moeda não estiver disponível na Binance.

Na prática: se é negociada em algum lugar e tem listagem no CoinGecko, vai funcionar.

Arquitetura

Stateless por design — sem banco de dados, sem agendador. Cada chamada de ferramenta busca dados frescos.

Claude (MCP call)
    └── server.py              FastMCP entry point
         ├── tools/
         │    ├── analyze.py        Orchestrates fetch → indicators → regime → score
         │    ├── rank.py           Runs analyze_coin in parallel, sorts by TSS
         │    ├── top_coins.py      Fetches top N by market cap, delegates to rank_coins
         │    ├── correlate.py      Pairwise Pearson correlation of 30-day returns
         │    ├── watchlist.py      Watchlist + alert tools (7 tools)
         │    ├── debate.py         Builds prompt from TA data, calls Claude API
         │    └── market_context.py ARS + MRS + macro signals
         ├── ta/
         │    ├── indicators.py     pandas-ta + custom HV / RS / OBV functions
         │    ├── scoring.py        TSS: trend + momentum + RS ± MTF ± OBV bonuses
         │    ├── regime.py         HMM-first regime classifier with rule-based fallback
         │    └── hmm_regime.py     GaussianHMM train / persist / classify / auto-retrain
         ├── market/
         │    └── context.py        BTC dominance, ETH/BTC, TOTAL3, F&G, ARS, MRS
         └── data/
              ├── binance.py        Binance klines + funding rate (1,200 req/min, no auth)
              ├── coingecko.py      CoinGecko client, 5-min TTL cache, OHLCV builder
              ├── alternative_me.py Fear & Greed Index (Alternative.me, 1-hr cache)
              ├── defillama.py      DefiLlama stablecoin supply history
              └── watchlist_db.py   SQLite watchlist + alert persistence (~/.cryptoscholar/)

Fluxo de dados para analyze_coin("SOL"):

Mapear símbolo → ID CoinGecko (SOL → solana)
Buscar OHLCV diário de 300 dias da Binance (SOLUSDT klines); fallback para CoinGecko se indisponível
Buscar OHLCV 4H de 200 barras da Binance para análise multi-timeframe
Buscar taxa de funding do perpétuo USDT-M na Binance Futures (null se não houver perpétuo)
Calcular todos os indicadores diários via pandas-ta (EMA, RSI, MACD, ADX, ATR, BB, HV, OBV, RS vs BTC)
Calcular tendência OBV (EMA-10 da inclinação do OBV nas últimas 5 barras)
Calcular indicadores 4H (EMA-20/50) e derivar bônus de alinhamento MTF (±3 pts TSS)
Detectar divergência RSI nas últimas 30 barras (altista/baixista/nenhuma)
Classificar regime via GaussianHMM (hv_20 + ATR normalizado + BBW); fallback baseado em regras se não houver modelo
Calcular TSS (composto ponderado de tendência, momentum, RS vs BTC ± bônus MTF ± bônus OBV)
Buscar dados de mercado atuais (preço, capitalização, mudança 24h) do CoinGecko
Retornar dicionário estruturado ao Claude

Fluxo de dados para market_context():

Buscar histórico de capitalização total do mercado (30d) do CoinGecko /global/market_cap_chart
Buscar histórico de gráficos de mercado BTC e ETH (30d) do CoinGecko
Buscar histórico de oferta de stablecoins do DefiLlama
Buscar Índice de Medo e Ganância do Alternative.me (cache de 1 hora)
Calcular tendência de dominância BTC, tendência da razão ETH/BTC, mudança TOTAL3
Pontuar em ARS (rotação de altcoins) e MRS (prontidão do mercado + modificador F&G)

Desenvolvimento

make test            # run test suite
make test-parallel   # run tests in parallel (pytest-xdist)
make coverage        # coverage report
make lint-security   # bandit security scan

222 testes, 0 falhas.

Roadmap

Veja ROADMAP.md para versões planejadas. Destaques:

v0.8 — research_coin ferramenta: busca na web + leitor Jina para notícias e contexto narrativo
v0.9 — Classificação de estrutura de mercado (HH/HL/LH/LL) via detecção de pontos de oscilação; novo campo market_structure em analyze_coin
v1.0 — Zonas de suporte e resistência agrupadas a partir de pivôs de oscilação; support_zones + resistance_zones em analyze_coin
v1.1 — Pontuação de confluência do setup (1–5) medindo o alinhamento dos sinais; exibida em analyze_coin, rank_coins, watchlist_scan
v1.2 — Bloco de plano de trade: entry_zone, take_profit, stop_loss, risk_reward_ratio calculados a partir das zonas de S/R + ATR
v1.3 — Indicador Pi Cycle em market_context; ferramenta brief: resumo do setup em um parágrafo via Claude Haiku
v1.4 — Filtro de EV: ev_score + ev_signal sinalizam setups com EV negativo antes de agir em um plano de trade
v1.5 — Ferramenta backtest_strategy: simulação walk-forward, R ajustado por taxas, taxa de acerto, drawdown máximo

Licença

MIT