Cryptoscholar

CryptoScholar

Claude 内で暗号資産のテクニカル分析を。 CryptoScholar は、Claude にリアルタイムのテクニカル分析機能を提供する Model Context Protocol (MCP) サーバーです。チャートの切り替えも、データのコピー＆ペーストも、コンテキストの喪失もありません。

Claude に 「SOL はスイングトレードに適した状態ですか？」 と尋ねると、Binance からライブデータを取得し、インジケーター一式を算出してスコアを付け、根拠に基づいた強気・弱気の議論を 1 回の応答ですべて提示します。

---

できること

CryptoScholar は、Claude がネイティブに呼び出せる 15 個の MCP ツールを提供します。

analyze_coin

任意のコインについて、テクニカル分析の全体像を取得します。Binance から過去 300 日分の実際の OHLCV ローソク足データを取得し（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 本の価格と RSI の高値・安値を比較
OBV トレンド	オンバランスボリュームの方向（上昇／下降／横ばい）— 確認用の ±2 TSS ボーナス
ファンディングレート	現在の USDT-M 無期限先物のファンディングレート — 極端なプラス値はロングの過剰レバレッジを示します
レジーム	低／中／高ボラティリティ — 3 状態 GaussianHMM で分類（ルールベースの方式にフォールバック）
TSS	トレンド強度スコア — 0～100 の合成スコア（トレンド 40% ＋ モメンタム 30% ＋ RS 30% ± 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 など）
• 1 日あたりの取引高が 1,000 万ドル未満の低流動性コイン

correlate_coins

2～20 種類のコインについて、30 日間の日次リターンのペアごとのピアソン相関係数を算出します。相関行列全体、高相関クラスター（>0.85）、無相関ペア（<0.30）を返します。ポートフォリオの分散分析に役立ちます。

market_context

個別のコイン分析に活用できるマクロ市場シグナルを提供します。CoinGecko のグローバルデータ、DefiLlama のステーブルコイン供給量、Alternative.me の Fear & Greed Index を使用して、以下を返します。

シグナル	説明
BTC ドミナンス	現在の割合と 30 日間の変化 — 低下は資金がアルトコインへ移っていることを示します
ETH/BTC 比率	20 日間のトレンド — 上昇は上昇相場の広がりを示します
TOTAL3	アルトコインの時価総額（BTC と ETH を除く）の 30 日間の変化
ステーブルコイン供給量	ステーブルコインの時価総額合計と 30 日間のトレンド（上昇は購買力の増加を示します）
Fear & Greed	Alternative.me の指数（0～100）— 極端な恐怖／強欲は MRS に ±5 の補正を適用します
ARS	アルトコイン・ローテーション・スコア 0～100 — マクロ環境がアルトコインにどれほど有利かを示します
MRS	市場準備度スコア 0～100 — 上昇に向けた市場全体の準備状況を示します

debate

Claude がライブのテクニカル分析データを読み取り、実際のインジケーター値に基づいた、構造化された強気・弱気の議論を生成します。根拠のない意見は生成しません。以下を返します。

• 強気シナリオ — テクニカル指標が有利な方向に示していること
• 弱気シナリオ — 起こりうるリスク
• 結論 — 1 文でまとめた見解

ウォッチリストツール

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

新しい BTC 価格履歴を使って、HMM ボラティリティレジームモデルの再学習を手動で開始します。モデルは 7 日ごとに自動で再学習されます。大きな市場構造の変化があった場合に、すぐに更新するために使用してください。7 日間のクールダウンを回避するための任意の force=True フラグを受け付けます。

generate_report

1 つ以上のコインについて、構造化された分析レポートを生成します。3 段階のパイプラインを使用します。

1. クラスタリング — TA シグナルをテーマ別のセクション（トレンド、モメンタム、出来高／オンチェーン、ボラティリティ、相対的な強さ）に分類します
2. 執筆 — Claude が分類されたシグナルに基づいて、各セクションの説明文を作成します
3. 組み立て — 各セクションをまとめ、冒頭に主要統計テーブルを含む書式付き Markdown レポートを作成します

単一コインの詳細分析と、複数コインの比較レポート（例：["BTC", "ETH", "SOL"]）に対応しています。Markdown の代わりに構造化された出力を得るには、output_format="json" を渡します。1 回の呼び出しにつき最大 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 に hmmlearn と scikit-learn が追加されました。これらはすでに pyproject.toml で必須になっていました。

---

v0.7.0 の新機能

• generate_report ツール（ツール #15） — クラスタリング → 執筆 → 組み立ての 3 段階パイプラインにより、任意のコインまたはコインリストについて、書式付き 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 銘柄を表示して」
• 「今のマクロ市場はどのような状況？」
• 「現在のテクニカル分析に基づいて、DOGE の強気シナリオと弱気シナリオを教えて」
• 「過去 1 か月間の BTC、ETH、SOL、AVAX の相関性はどのくらい？」
• 「BTC、ETH、SOL をメインのウォッチリストに追加して」
• 「TSS が 35 を下回ったら BTC のアラートを設定して」
• 「アラートを確認して」
• 「メインのウォッチリストのダイジェストを教えて」

---

スクリーンショット

トレンド強度スコアで BTC、ETH、XRP を順位付けし、その後 XRP の弱気シナリオを詳しく分析

rank_coins は、トレンド、モメンタム、BTC に対する相対的な強さに基づいて各銘柄をスコア化し、TSS の高い順に返します。この例では、すべて low_vol レジームで、BTC が 63.7、ETH が 53.0、XRP が 47.8 です。その直後に XRP の弱気シナリオを尋ねると、週足 EMA の傾きが最も急であること、MACD が弱まっていること、ETH の BTC に対するパフォーマンスの低下が機関投資家の早期撤退圧力として示されていることなど、具体的なテクニカル上の理由がすぐに提示されます。

---

SOL のテクニカル分析スナップショット — 指標、スコア、弱気シナリオを 1 回の応答にまとめて表示

analyze_coin は、EMA の並びと整合性、RSI、MACD、ADX、ATR、ボリンジャーバンド幅、OBV のトレンド、ファンディングレート、BTC に対する相対的な強さを網羅した、構造化された内訳を返します。すべて、Binance の過去 300 日分の最新ローソク足から計算されます。その後 Claude は、生の指標値を読み取り、EMA-200 の抵抗線、週足の傾きの強まり、MACD のデッドクロスリスクを根拠とした弱気シナリオを生成します。チャートを切り替えたり、コピー＆ペーストしたりする必要はありません。テクニカル分析の全コンテキストが、すでに 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 DB のディレクトリです

---

対応銘柄

CryptoScholar は CoinGecko または Binance に掲載されているあらゆる銘柄に対応しています。ティッカーシンボルを渡すだけで使えます。設定は不要です。

組み込みのシンボルマップには、即時に照合できる主要 65 銘柄が登録されています。これには、BTC、ETH、SOL、BNB、XRP、ADA、AVAX、DOGE、LINK、DOT、SUI、TIA、WIF、BONK など、時価総額上位 50 銘柄すべてが含まれます。それ以外の銘柄については、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 のローソク足）。利用できない場合は CoinGecko にフォールバックします
3. マルチタイムフレーム分析用に、Binance から200本分の4時間足 OHLCV を取得します
4. Binance Futures から USDT-M 無期限先物の資金調達率を取得します（無期限先物がない場合は null）
5. pandas-ta で日次インジケーターをすべて計算します（EMA、RSI、MACD、ADX、ATR、BB、HV、OBV、BTC に対する RS）
6. OBV のトレンドを計算します（直近5本のローソク足における OBV の EMA-10 の傾き）
7. 4時間足インジケーター（EMA-20/50）を計算し、MTF アラインメントボーナス（TSS ポイント ±3）を導き出します
8. 直近30本のローソク足で RSI ダイバージェンスを検出します（強気／弱気／なし）
9. GaussianHMM（hv_20 + 正規化 ATR + BBW）でレジームを分類します。モデルがない場合はルールベースの方式にフォールバックします
10. TSS を計算します（トレンド、モメンタム、BTC に対する RS の加重複合値 ± MTF ボーナス ± 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 から Fear & Greed Index を取得します（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 リーダー
• 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 によるセットアップ概要の1段落要約
• v1.4 — EV フィルター：取引計画の実行前に、マイナス EV のセットアップを示す ev_score + ev_signal フラグ
• v1.5 — backtest_strategy ツール：ウォークフォワードシミュレーション、手数料調整後 R、勝率、最大ドローダウン

---

ライセンス

MIT