Cryptoscholar

CryptoScholar

直接在 Claude 中进行加密货币技术分析。 CryptoScholar 是一个模型上下文协议（MCP）服务，为 Claude 提供实时 TA 能力——无需切换图表、复制粘贴数据，也不会丢失上下文。

向 Claude 提问 “SOL 适合做波段交易吗？”，它就会从 Binance 获取实时数据，运行完整的指标套件并评分，然后在一条回复中给出有实际数据支撑的看涨／看跌辩论。

---

功能介绍

CryptoScholar 提供 15 个 MCP 工具，Claude 可原生调用：

analyze_coin

为任意币种生成完整的技术分析快照。从 Binance 获取 300 天的真实 OHLCV K 线（也可回退到 CoinGecko），并计算：

指标	详情
趋势	EMA-20、EMA-50、EMA-200 排列情况 + 周线 EMA 斜率
动量	RSI-14、MACD（线／信号线／柱状图）、ADX-14
波动率	ATR-14、布林带宽度、历史波动率（20 天年化）
相对强度	币种相对于 BTC 的表现（20 天比率变化）
多时间周期	4H EMA 排列情况——根据 4H EMA-20 与 EMA-50 的比较，给予 ±3 TSS 奖励／惩罚
RSI 背离	看涨／看跌／无——对比过去 30 根 K 线中的价格与 RSI 极值
OBV 趋势	能量潮方向（上升／下降／持平）——±2 TSS 确认奖励
资金费率	当前 USDT-M 永续合约资金费率——正向极端值表示多头杠杆过高
市场状态	低／中／高波动率——通过 3 状态 GaussianHMM 分类（无法使用时回退到基于规则的分类）
TSS	趋势强度评分——0–100 综合评分（40% 趋势 + 30% 动量 + 30% RS ± MTF ± OBV）

rank_coins

传入一组交易对符号，按 TSS 排序返回。采用并行处理（最多 8 个工作线程），可快速处理大型列表。每条结果都包含 TSS、市场状态、EMA 排列情况、4H MTF 排列情况、RSI 背离、OBV 趋势、资金费率、RSI-14、ADX-14 以及相对于 BTC 的 RS。

top_coins

无需提供交易对符号列表。从 CoinGecko 获取按市值排名的前 50 个币种，并按 TSS 排序返回。智能筛选会自动移除：

• 稳定币（USDT、USDC、DAI 等）
• 包装代币／合成代币（WBTC、WETH、stETH、cbBTC 等）
• 日交易量低于 $10M 的低流动性币种

correlate_coins

计算 2–20 个币种的 30 天日收益率两两 Pearson 相关系数。返回完整的相关系数矩阵、高相关性集群（>0.85）以及不相关的币种对（<0.30），可用于投资组合多元化分析。

market_context

提供宏观市场信号，为单个币种的分析提供背景。数据来源包括 CoinGecko 全球数据、DefiLlama 稳定币供应量以及 Alternative.me 恐惧与贪婪指数。返回：

信号	说明
BTC 主导率	当前占比及 30 天变化——下降表示资金正轮动至山寨币
ETH/BTC 比率	20 天趋势——上升表示涨势正在扩大
TOTAL3	山寨币市值（不含 BTC、ETH）的 30 天变化
稳定币供应量	稳定币总市值及 30 天趋势（上升表示购买力增强）
恐惧与贪婪指数	Alternative.me 指数（0–100）——极度恐惧／贪婪会对 MRS 施加 ±5 的调整
ARS	山寨币轮动评分 0–100——衡量宏观环境对山寨币的利好程度
MRS	市场准备度评分 0–100——衡量市场整体向上行情的准备程度

debate

Claude 读取实时 TA 数据，并基于实际指标值生成结构化的看涨／看跌辩论，而非凭空捏造观点。返回：

• 看涨观点——技术指标显示的利好因素
• 看跌观点——可能出现的问题
• 结论——一句话总结

自选列表工具

存储在 SQLite (~/.cryptoscholar/watchlist.db) 中的持久化币种列表。

工具	功能
watchlist_add	将币种代码添加到指定列表（若列表不存在则创建）
watchlist_remove	移除币种代码；同时清除其提醒
watchlist_show	显示指定列表中的所有币种代码及已配置的提醒
watchlist_lists	列出所有命名的自选列表及其币种数量
watchlist_scan	对列表中的每种币运行完整的 TSS 分析——并行摘要视图
alert_set	为任意币种设置 tss_above、tss_below 或 regime_change 提醒
alert_check	获取所有设有提醒的币种的实时 TA，报告触发的提醒并更新基线

train_regime_model

手动触发 HMM 波动率状态模型的重新训练，使用最新的 BTC 价格历史数据。模型每 7 天会自动重新训练一次——在市场结构发生重大变化后，可使用此工具立即更新。可选传入 force=True 标志，绕过 7 天冷却期。

generate_report

为一种或多种币生成结构化分析报告。采用 3 阶段流程：

1. 聚类 — 将 TA 信号归入主题板块（趋势、动量、成交量／链上、波动率、相对强度）
2. 撰写 — Claude 根据聚类后的信号，为每个板块撰写一段分析文字
3. 组装 — 将各板块整合为格式化的 Markdown 报告，并在顶部添加关键统计数据表

支持单币深度分析和多币对比报告（例如 ["BTC", "ETH", "SOL"]）。传入 output_format="json" 可获取结构化输出，而非 Markdown。每次调用最多支持 10 个币种代码。

获取市场数据无需 API 密钥。debate 和 generate_report 工具需要 ANTHROPIC_API_KEY。

---

v0.7.1 新增内容

• 需要 mcp 2.x SDK (mcp>=2.2.0,<3)。 服务端现使用 MCPServer（此前为 FastMCP）。Claude Code 2.1.282+ 会通过 2026 年的 server/discover 探测建立连接；此前 mcp 1.x 会将其记录为“Failed to validate request”警告，然后回退。已有安装用户请运行：pip install -U 'mcp>=2.2.0,<3'。工具名称和输入架构保持不变。
• 修复：状态模型文件采用原子写入。 HMM 模型之前会直接覆盖保存，因此并发调用可能读取到空文件，并静默回退到基于规则的分类器，直到下一次重新训练；现在并发调用时也只会执行一次重新训练（2.x 会在工作线程上运行工具）。
• requirements.txt 现在列出了 pyproject.toml 已要求的 hmmlearn 和 scikit-learn。

---

v0.7.0 新增内容

• generate_report 工具（工具 #15） — 采用“聚类 → 撰写 → 组装”三阶段流程，为任意一种或多种币生成格式化的 Markdown 报告。第 1 阶段将 TA 信号归入主题类别；第 2 阶段使用 Claude 撰写分析内容；第 3 阶段整合报告并添加关键统计数据表。
• 多币对比 — 最多传入 10 个币种代码，即可生成对比报告，其中包含各币种摘要、最佳／最弱形态判断，以及整体对比摘要。
• JSON 输出选项 — 传入 output_format="json"，即可获取完整的结构化报告字典，而非 Markdown，便于后续处理。
• 并行分析 — 在 Claude 撰写阶段之前，会并行获取多币种报告所需的币种数据（最多使用 8 个工作线程）。

---

快速开始

要求： Python 3.11+，mcp SDK 2.2+

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

添加到 Claude Code

在 ~/.claude/.mcp.json 中：

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

重启 Claude Code。现在你可以询问：

• “帮我分析 BTC”
• “按趋势强度对 ETH、SOL、AVAX 和 LINK 排名”
• “显示按趋势强度排名的前 50 种币”
• “当前宏观市场行情如何？”
• “根据当前 TA，分析 DOGE 的看涨和看跌理由”
• “过去一个月 BTC、ETH、SOL 和 AVAX 的相关性如何？”
• “将 BTC、ETH 和 SOL 添加到我的主观察列表”
• “如果 BTC 的 TSS 跌破 35，就设置提醒”
• “检查我的提醒”
• “提供我的主观察列表简报”

---

截图

按趋势强度评分对 BTC、ETH 和 XRP 排名，然后深入分析 XRP 的看跌理由

rank_coins 会根据趋势、动量以及相对于 BTC 的强弱对每种币评分，并按 TSS 排序。这里 BTC 以 63.7 领先，ETH 为 53.0，XRP 以 47.8 落后——它们都处于 low_vol 市场状态。随后询问 XRP 的看跌理由，会立即揭示具体的技术原因：每周 EMA 斜率最陡、MACD 走弱，以及 ETH 相对于 BTC 表现不佳，这被标记为机构资金早期离场压力。

---

SOL 的完整技术分析快照——在一次回复中呈现指标、评分和看跌理由

analyze_coin 会返回结构化分析，涵盖 EMA 堆叠排列、RSI、MACD、ADX、ATR、布林带宽度、OBV 趋势、资金费率以及相对于 BTC 的强弱——所有数据均根据 Binance 的 300 天实时 K 线计算得出。Claude 随后会读取原始指标值，生成有据可依的看跌分析：EMA-200 阻力、周线斜率加陡，以及 MACD 向下交叉风险。无需切换图表，也无需复制粘贴——完整的 TA 背景已在 Claude 窗口中呈现。

---

输出示例

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."
}

---

配置

变量	默认值	说明
ANTHROPIC_API_KEY	—	debate 工具必需
CRYPTOSCHOLAR_MODEL	claude-haiku-4-5-20251001	用于辩论的 Claude 模型（可替换为 Sonnet/Opus 以进行更深入的分析）
CRYPTOSCHOLAR_LOG_DIR	/tmp	轮换日志文件的目录
CRYPTOSCHOLAR_DATA_DIR	~/.cryptoscholar	观察列表 SQLite 数据库的目录

---

支持的币种

CryptoScholar 支持 CoinGecko 或 Binance 上列出的任何币种——只需传入代码即可。无需配置。

内置符号映射可即时解析 65 种主流币，涵盖完整的市值排名前 50 的币种，包括 BTC、ETH、SOL、BNB、XRP、ADA、AVAX、DOGE、LINK、DOT、SUI、TIA、WIF、BONK 等。对于列表之外的币种，CryptoScholar 会自动查询 CoinGecko 搜索 API 来解析符号；如果 Binance 上没有该币种，则会回退到 CoinGecko OHLCV。

实际来说：只要某种币在某处有交易，且在 CoinGecko 上有列表，就能使用。

---

架构

采用无状态设计——没有数据库，也没有调度器。每次工具调用都会获取最新数据。

Claude (MCP call)
    └── server.py              MCPServer 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/)

analyze_coin("SOL") 的数据流：

1. 将代号映射为 CoinGecko ID（SOL → solana）
2. 从 Binance 获取 300 天的日线 OHLCV 数据（SOLUSDT K 线）；如果不可用，则回退到 CoinGecko
3. 从 Binance 获取 200 根 4 小时 OHLCV 数据，用于多时间框架分析
4. 从 Binance Futures 获取 USDT-M 永续合约资金费率（无永续合约时为 null）
5. 通过 pandas-ta 计算所有日线指标（EMA、RSI、MACD、ADX、ATR、BB、HV、OBV、相对 BTC 强弱）
6. 计算 OBV 趋势（过去 5 根 K 线的 OBV EMA-10 斜率）
7. 计算 4 小时指标（EMA-20/50），并得出多时间框架对齐加分（±3 TSS 分）
8. 检测过去 30 根 K 线的 RSI 背离（看涨／看跌／无）
9. 通过 GaussianHMM 判断市场状态（hv_20 + 归一化 ATR + BBW）；无模型时回退到基于规则的判断
10. 计算 TSS（趋势、动量、相对 BTC 强弱的加权综合分 ± 多时间框架加分 ± OBV 加分）
11. 从 CoinGecko 获取当前市场数据（价格、市值、24 小时涨跌幅）
12. 将结构化字典返回给 Claude

market_context() 的数据流：

1. 从 CoinGecko /global/market_cap_chart 获取总市值历史数据（30 天）
2. 从 CoinGecko 获取 BTC 和 ETH 的市场图表历史数据（30 天）
3. 从 DefiLlama 获取稳定币供应量历史数据
4. 从 Alternative.me 获取恐惧与贪婪指数（缓存 1 小时）
5. 计算 BTC 市占率趋势、ETH/BTC 比率趋势和 TOTAL3 涨跌幅
6. 计算 ARS（山寨币轮动）和 MRS（市场就绪度 + F&G 修正值）评分

---

开发

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 项测试，0 个失败。

---

路线图

计划中的版本请参阅 ROADMAP.md。主要内容：

• v0.8 — research_coin 工具：通过网络搜索和 Jina reader 获取新闻和叙事背景
• v0.9 — 通过摆动点检测进行市场结构分类（HH/HL/LH/LL）；在 analyze_coin 中新增 market_structure 字段
• v1.0 — 根据摆动枢轴点聚类支撑位和阻力位区域；在 analyze_coin 中新增 support_zones + resistance_zones
• v1.1 — 设置共振评分（1–5），衡量信号一致性；在 analyze_coin、rank_coins、watchlist_scan 中展示
• v1.2 — 交易计划模块：根据 S/R 区域 + ATR 计算 entry_zone、take_profit、stop_loss、risk_reward_ratio
• v1.3 — 在 market_context 中加入 Pi Cycle 指标；新增 brief 工具：由 Claude Haiku 生成一段式设置摘要
• v1.4 — EV 筛选器：通过 ev_score + ev_signal 标记负期望值设置，在执行交易计划前发出提示
• v1.5 — backtest_strategy 工具：滚动前推模拟、费用调整后的 R 值、胜率、最大回撤

---

许可证

MIT