bitbank-lab-mcp

bitbank API のデータを使った暗号資産市場分析を、Claude / Cursor / Codex / Antigravity CLI など各種 AI クライアントから簡単に実行できる MCP サーバーです。

はじめにお読みください

• 本ツールは開発段階（ベータ版）です。利用は自己責任でお願いします。

• ご利用の前に必ず ⚠️ 免責事項 をお読みください。

• 本リポジトリは bitbank バグバウンティプログラムの対象範囲外 です。

Related MCP server: bitbank MCP Server

本 MCP サーバーについて

bitbank の公開 API から取得した価格・取引データを、指標計算・統合・可視化用データの整形まで行った上で LLM に渡します（必要に応じてサーバー側で SVG 描画も可能）。生データを渡すだけのサーバーとは異なり、各ツールの description に「いつ使うべきか」「他ツールとの使い分け」を明示しているため、LLM が自律的に適切なツールを選択できます。

姉妹プロジェクトとして、同じ bitbank API に対する真逆のアプローチを提供する CLI (bitbank-lab-cli) もあります。

• この MCP サーバー はサーバー側で計算済みの結論を LLM に渡す

• CLI は生データを高速に取得し、LLM 自身に計算させる

指標のパラメータやロジックを完全にカスタマイズしたい場合は CLI 側を、すぐに使えるテクニカル分析・可視化を求める場合は MCP サーバー側を選んでください。

概要

bitbank の公開 API から価格・板情報・約定履歴・ローソク足データを取得し、以下の分析を実行できます。
→ 全ツールの一覧と使い分けは docs/tools.md を参照。

取得できるデータ

• リアルタイム価格（ティッカー）

• 板情報（オーダーブック）

• 約定履歴（売買方向・時刻）

• ローソク足（1分足〜月足）

実行できる分析

• テクニカル指標（SMA/RSI/ボリンジャーバンド/一目均衡表/MACD）

• フロー分析（買い/売りの勢い・CVD・スパイク検出）

• ボラティリティ分析（RV/ATR）

• 板の圧力分析（価格帯ごとの買い/売り圧力）

• パターン検出（ダブルトップ/ヘッドアンドショルダーズ等）

• 総合スコア判定（複数指標を統合した強弱判定）

  • 長期パターンの現在地関連検出（detect_patterns: requireCurrentInPattern/currentRelevanceDays）

視覚化

• Claude.ai の Visualizer で描画するためのコンパクトな整形データを返すツール群

  • prepare_chart_data: ローソク足 + 指標の時系列データ

  • prepare_depth_data: 板の累積 volume 階段データ

• ファイル保存・Cursor 等の非 Visualizer 環境向けに SVG/PNG 形式のチャートも生成可能

  • render_chart_svg / render_depth_svg / render_candle_pattern_diagram

クイックスタート

前提条件

• Node.js 22 以上（24 推奨）

  • node -v で確認できます

  • 公式サイト からインストール

• npm（Node.js に同梱されています）

• 対応 OS: macOS / Linux / Windows（WSL 含む）

• Claude Desktop アプリを Claude 公式サイト からダウンロードしてください

本プロジェクトは npm に bitbank-lab-mcp として公開されています。
ソースコードのクローンは不要です（開発したい方向けの手順は末尾の開発者向けセクションを参照）。

1. Claude Desktop に登録（推奨）

Claude Desktop が最も多くの方が使う想定の MCP クライアントです。
~/Library/Application Support/Claude/claude_desktop_config.json に設定を追加します。

登録方法は2通りあります。まず npx 方式を試し、動かない場合に絶対パス方式をお試しください。

npx 方式（推奨）

Node.js のバージョンアップで設定を書き換える必要がないため、こちらを推奨します。
nvm/volta などのバージョン管理ツールをお使いの方には特におすすめです。

用途に応じて A〜C の 3 段階から選びます。

A. Public データのみ:

価格・板・ローソク足などの公開市場データの取得と分析。API キー不要。

{
  "mcpServers": {
    "bitbank-lab": {
      "command": "npx",
      "args": ["-y", "bitbank-lab-mcp"]
    }
  }
}

B. Private データ参照系（要 API キー）:

資産残高・約定履歴・注文照会・ポートフォリオ分析などの読み取り専用。発注はできません。

{
  "mcpServers": {
    "bitbank-lab": {
      "command": "npx",
      "args": ["-y", "bitbank-lab-mcp"],
      "env": {
        "BITBANK_API_KEY": "your_api_key",
        "BITBANK_API_SECRET": "your_api_secret"
      }
    }
  }
}

✅ bitbank API の権限は「参照」のみ設定することを推奨

C. 取引注文・注文キャンセル実行（要 API キー）:

B に加えて、AI からの発注・注文キャンセルまで実行。実行前に必ず確認ステップ（preview → execute の 2 段階確認）が入ります。

{
  "mcpServers": {
    "bitbank-lab": {
      "command": "npx",
      "args": ["-y", "bitbank-lab-mcp"],
      "env": {
        "BITBANK_API_KEY": "your_api_key",
        "BITBANK_API_SECRET": "your_api_secret",
        "BITBANK_TRUST_HOST_APPROVAL": "1"
      }
    }
  }
}

✅ bitbank API の権限は「参照」および「取引」のみ設定することを推奨

※ 「出金」権限は有効化しないことを強く推奨します。本サーバーは出金系ツール未実装のため不要です。

BITBANK_TRUST_HOST_APPROVAL（値は文字列の "1" のみ有効）は、Claude Desktop の確認ボタンから発注/キャンセルを実行できるようにするオプトインです。有効化すると確認トークンが LLM からも見える経路で返るため、理論上は LLM が確認ボタンを経ずに実行を試みる余地を受け入れることになります。ただしトークンはプレビューした注文 1 件のみ有効・期限 60 秒・使い捨てで、実行前には毎回ホストの承認ダイアログが最終ゲートとして入るため、影響は限定的です。このゲートを保つため、取引ツールは「常に許可（Always allow）」にせず毎回確認してください。

詳細: ADR-0007 / Private API ガイド。

B / C の API キーは bitbank 設定画面 で発行し、必要最小限の権限のみを付与、可能なら IP 制限も設定してください（最小権限の原則）。

詳細: Private API ガイド。

絶対パス方式（フォールバック）

npx 方式で「サーバーに接続できません」エラーが出る場合、Claude Desktop から npx コマンドが見つけられていない可能性があります。
その場合は、npx の絶対パスを指定してください。

まずターミナルで自分の環境の npx パスを確認します：

which npx

出力例と対応するインストール方法：

which npx の結果を command に指定：

{
  "mcpServers": {
    "bitbank-lab": {
      "command": "<which npx の出力>",
      "args": ["-y", "bitbank-lab-mcp"]
    }
  }
}

⚠️ nvm/volta ユーザーへの注意: この方式では Node.js をバージョンアップするたびに command のパスの書き換えが必要です（例: v24.0.0 → v24.1.0）。アップデート後に which npx を再確認してください。

Windows の場合

Windows でも npx 方式がそのまま使えます：

{
  "mcpServers": {
    "bitbank-lab": {
      "command": "npx",
      "args": ["-y", "bitbank-lab-mcp"]
    }
  }
}

設定ファイルの場所: %APPDATA%\Claude\claude_desktop_config.json

npx が見つからない場合は where npx（Windows 版の which）で絶対パスを確認して指定してください。

表示名のカスタマイズ

Claude Desktop の UI に表示される名前は claude_desktop_config.json のキー名で決まります：

{
  "mcpServers": {
    "bitbank-lab-mcp": {
      "command": "npx",
      "args": ["-y", "bitbank-lab-mcp"]
    }
  }
}

⚠️ bitbank-lab-mcp のような ASCII（英数字）の名前を推奨します。環境によって、日本語などの非 ASCII 名だと Chat でツールが見つからない事例があります。

共通の注意事項

• 追加後、Claude Desktop を Cmd+Q（Windows は完全終了）で再起動してください

• ⚠️ macOS で claude_desktop_config.json が見つからない場合は、ホームディレクトリ直下から開いてください

設定ファイルの場所：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

2. その他の MCP クライアント（手動 .json 編集）

Cursor（.cursor/mcp.json）

{
  "mcpServers": {
    "bitbank-lab": {
      "command": "npx",
      "args": ["-y", "bitbank-lab-mcp"],
      "env": {
        "BITBANK_API_KEY": "your_api_key",
        "BITBANK_API_SECRET": "your_api_secret"
      }
    }
  }
}

API キーが不要な場合は env ブロックごと削除して OK。セクション 1 の A〜C と同様に、取引実行まで使う場合のみ BITBANK_TRUST_HOST_APPROVAL を検討してください。

Claude Code（CLI から登録する場合）

claude mcp add --transport stdio bitbank-lab -- npx -y bitbank-lab-mcp

同梱 Skill も一緒に使いたい場合は、セクション 3 の plugin install が便利です。

Windsurf / その他の汎用 MCP クライアント

Cursor と同じ JSON 形式で登録できます。クライアント固有の設定ファイルパスについては各クライアントのドキュメントを参照してください。

3. （オプション）Plugin として install（同梱 Skill を使う）

通常の利用はセクション 1〜2 の登録だけで完結します。Plugin install は、Claude Code などの AI コーディングツールで、MCP サーバーに加えて同梱 Skill（skills/ 配下）も使いたい方向けのオプションです。

• Plugin として install すると、MCP ツールと同時に同梱 Skill（例: investment-onboarding）が有効化されます。今後 Skill を追加した場合も、plugin のアップデートでまとめて届きます。

• Skill を自作してワークフローをカスタマイズしたい方は、skills/INDEX.md の構成が参考になります。

• Claude Desktop は plugin / Skill の読み込みに未対応です。Claude Desktop で使う場合はセクション 1 の方法で登録してください（MCP ツールの機能は同じで、Skill が使えるかどうかだけの違いです）。

いずれの manifest も npm registry の bitbank-lab-mcp を npx -y 経由で起動します。

Gemini CLI は 2026-06-18 に個人アカウント向け提供を終了し、Antigravity CLI（agy）に移行しました。Antigravity CLI は旧 Gemini CLI 拡張（gemini-extension.json）を後方互換で読み込みます（agy plugin import gemini でネイティブ plugin へ変換も可能）。

Claude Code の例:

# 1. このリポジトリを marketplace として登録（初回のみ）
/plugin marketplace add bitbankinc/bitbank-lab-mcp

# 2. plugin を install
/plugin install bitbank-lab-mcp@bitbank-lab

# 3. plugin を有効化
/reload-plugins

bitbank-lab はこのリポが提供する marketplace 名（.claude-plugin/marketplace.json の name フィールド）、bitbank-lab-mcp は plugin 名です。

実行後、bitbank API key / API secret の入力 UI が表示されます。Public ツールだけで使う場合は両方とも空欄で OK — Private API ツールは API キーを入力したときだけ自動的に有効化されます。

API キーを後から追加・変更したい場合は /plugin から該当 plugin の設定を開き、api_key / api_secret を更新してください。Claude Code では sensitive: true のため OS のキーチェーンに保管されます。

Cursor / Codex の場合（環境変数経由）:

/plugin install 実行後、シェルで以下のように環境変数を設定してから Cursor / Codex を起動してください（Public ツールだけ使う場合は不要）:

export BITBANK_API_KEY="your_api_key"
export BITBANK_API_SECRET="your_api_secret"

macOS / Linux では ~/.zshrc や ~/.bashrc に書いておくと永続化されます。Windows は環境変数の管理画面 or setx を使用してください。

4. 使ってみる

AI クライアントにそのまま話しかけます:

BTCの今の市場状況を分析して
ビットコインは買いと売りどちらが優勢？
直近 1 週間でテクニカル的に上向きの仮想通貨を 3 つ教えて

💡 何を聞けばいいかわからない場合: 用意されたプロンプト集 をご覧ください。初心者向け（🔰）から中級者向けまで、9種類の分析プロンプトを用意しています。

🌅 朝のルーティンに: 「おはようレポート」で、寝ている間の相場変動をすばやくキャッチアップできます。

Private API（取引機能）

API キーの有無でサーバーが公開する機能が自動的に切り替わります。

キー未設定時、Private ツール・プロンプトは MCP クライアントに一切表示されません（エラーではなく、そもそも登録されません）。公開データの取得・分析だけなら設定不要で、そのまま使えます。

環境変数の設定方法

ターミナルから起動する場合:

export BITBANK_API_KEY="your_api_key"
export BITBANK_API_SECRET="your_api_secret"

Plugin install を使った場合 — /plugin から該当 plugin の設定を開き、api_key / api_secret を入力すれば完了です（手動編集は不要）。

Claude Desktop で手動設定している場合 — claude_desktop_config.json の env に追加（セクション 1 で設定した npx 方式／絶対パス方式のいずれかに、以下のように BITBANK_API_KEY と BITBANK_API_SECRET を追加するだけです）:

{
  "mcpServers": {
    "bitbank-lab": {
      "command": "npx",
      "args": ["-y", "bitbank-lab-mcp"],
      "env": {
        "BITBANK_API_KEY": "your_api_key",
        "BITBANK_API_SECRET": "your_api_secret"
      }
    }
  }
}

API キーは bitbank 設定画面 で発行してください。必要最小限の権限のみ付与することを強く推奨します（最小権限の原則）。

⚠️ 「出金」権限は絶対に有効化しないでください。本 MCP サーバーは出金系ツールを実装していないため、この権限を付ける必要は一切ありません。漏洩時の資産流出を避けるためです。

IP 制限: bitbank 側で API キーに IP 制限を設定できる場合は、可能な限り設定を推奨します。

取引操作（発注・キャンセル）は preview → execute の2ステップ確認が必須です。preview ツールが発行する確認トークン（HMAC-SHA256、デフォルト60秒有効）なしでは実行できません。

詳細: docs/private-api.md

使用例（会話の型）

• 「今、BTC は買いですか？」→ analyze_market_signal: 総合スコア + 寄与度・根拠

• 「直近で MACD クロスした銘柄は？」→ detect_macd_cross: スクリーニング結果

• 「ここ 30 日のボラ推移を見たい」→ get_volatility_metrics + render_chart_svg

チャート表示（SVG）

• MCP クライアント（Claude）では、アーティファクトとして data.svg を表示するようにお願いしてください。

  • Claude で LLM がうまくアーティファクトを出力できない場合は、以下のプロンプトを加えるのがおすすめです。

    • 「identifier と title を追加して、アーティファクトとして表示して」

  • 既定の描画は「ロウソク足のみ」。ボリンジャーバンド等のオーバーレイは明示指定時に追加されます（BBは --bb-mode=default 指定時に ±2σ がデフォルト）。

詳細ドキュメント

• プロンプト集（初心者〜中級者向け）: docs/prompts-table.md

• ツール一覧と使い分け: docs/tools.md

• Private API ガイド: docs/private-api.md

• 変更履歴: CHANGELOG.md

• 開発者向けガイド（型生成・CI など）: CLAUDE.md

• 運用・監視（ログ集計／Docker起動 ほか）: docs/ops.md

よくある質問（FAQ）

Q. 何を聞けばいいかわからない プロンプト集 を参照してください。初心者向け🔰から中級者向けまで9種類の分析プロンプトを用意しています。

Q. Docker は必須？ いいえ。Node 18+ でローカル実行できます（最短は Claude Desktop 登録）。

Q. API キーは必要？ 公開データの取得・分析には不要です。自分の資産確認や注文操作（Private API）を使う場合は Private API ガイド を参照してください。

Q. どのツールを使えばよい？ まず analyze_market_signal で全体を把握 → 必要に応じて各専門ツールへ。

Q. 対応銘柄は固定？ 固定ではありません。上流の公開 API が返す銘柄に自動追随します（追加/廃止も自動反映）。参考: bitbank 公開API仕様

Q. MCP Inspector でも試せる？ はい。次で実行できます（npm 公開版に対する動作確認）。

npx @modelcontextprotocol/inspector -- npx -y bitbank-lab-mcp

ソースコードから動かす場合は npx @modelcontextprotocol/inspector -- tsx src/server.ts（開発者向け を参照）。

Q. 当日の約定（フロー）データが少ない・古い時間帯が取れない bitbank 側の仕様です。約定履歴の日付アーカイブ（/transactions/{YYYYMMDD}）は UTC 暦日単位で、当該 UTC 日の完了後（日本時間 9:00 以降、さらに公開遅延あり）にのみ公開されます。進行中の UTC 日の約定は直近約 60 件（latest）しか取得できないため、get_flow_metrics 等では当日区間のカバレッジが限定的になります（結果に warning として明示されます）。ローソク足（get_candles）は進行中の UTC 日でもリアルタイムで取得できます。

トラブルシューティング

開発者向け（ソースから起動）

このセクションは「自分で MCP サーバーをいじりたい」「PR を送りたい」という開発者向けです。通常の利用者はセクション 1 の npx -y bitbank-lab-mcp 方式で OK です（こちらは clone 不要）。

セットアップ

git clone https://github.com/bitbankinc/bitbank-lab-mcp.git
cd bitbank-lab-mcp
npm ci

package-lock.json 通りに依存をインストールするため、ローカル開発でも npm install ではなく npm ci を推奨します（CI も npm ci を使用）。

ビルドステップは不要です（tsx で TypeScript を直接実行します）。

STDIO モード（Claude Desktop / Claude Code 向け）

ローカルの開発版を Claude Desktop から使いたい場合、claude_desktop_config.json に絶対パス指定で登録します：

{
  "mcpServers": {
    "bitbank-dev": {
      "command": "npx",
      "args": ["tsx", "/ABS/PATH/to/src/server.ts"],
      "workingDirectory": "/ABS/PATH/to/project",
      "env": { "LOG_LEVEL": "debug", "NO_COLOR": "1" }
    }
  }
}

/ABS/PATH/to/ を実際のクローン先パス（pwd で確認）に置き換えてください。npm 公開版（bitbank-lab）と区別するため、サーバー名は bitbank-dev 等にしておくと両立できます。

Inspector で動作確認する場合:

npx @modelcontextprotocol/inspector -- tsx src/server.ts

Windows でローカル開発する場合

npx が PATH 解決できない環境では、node の絶対パスと tsx の CLI を直接指定します：

{
  "mcpServers": {
    "bitbank-dev": {
      "command": "node",
      "args": [
        "C:\\Users\\<USERNAME>\\bitbank-lab-mcp\\node_modules\\tsx\\dist\\cli.mjs",
        "C:\\Users\\<USERNAME>\\bitbank-lab-mcp\\src\\server.ts"
      ],
      "workingDirectory": "C:\\Users\\<USERNAME>\\bitbank-lab-mcp",
      "env": { "LOG_LEVEL": "debug", "NO_COLOR": "1" }
    }
  }
}

CI / 型生成 / リンター

開発時のコマンド一覧は CLAUDE.md を参照してください（npm test / npm run lint:fix / npm run gen:types 等）。

フィードバック・バグ報告

バグ報告や機能要望は GitHub Issues からお願いします。Issue テンプレートを用意していますので、用途に合ったものを選択してください。

免責事項

開発段階について

本ツールは開発段階（ベータ版）です。バグ、不具合、誤動作、または不正確な分析結果を含む可能性があります。

AI エージェントによる処理結果について

本MCPサーバー / 本CLIツール が提供するデータを AIエージェント等が処理・生成した結果について、正確性、完全性、有用性、最新性を保証するものではありません。AI エージェント等による処理の結果、注文種別、価格、数量その他の取引条件が利用者の意図と異なる形で処理または実行される可能性があります。

金融商品取引法上の位置づけ

本MCPサーバーは情報提供のみを目的として提供されるものであり、投資助言・代理業、投資勧誘、その他金融商品取引法上の行為を目的とするものではありません。

外部サービスへの依拠

本MCPサーバーは外部API、LLM、第三者サービス等に依拠して提供するものであり、これらの仕様変更、停止、不具合等が生じた場合には、本MCPサーバーが正常に動作しない可能性があります。

安全対策の補助性

本MCPサーバーに実装されている最終注文確認機能、バリデーションその他の安全対策は、誤操作または誤発注等を防止するための補助機能であり、その完全な防止を保証するものではありません。

利用者の責任

利用者は、本MCPサーバーにより提供・生成された情報および注文内容等を自身で十分に確認の上、自己の判断と責任において本MCPサーバーを利用し、投資判断、注文実行および取引を行うものとします。

損害の免責

当社は、本MCPサーバーの利用もしくは利用不能、または本MCPサーバーにより提供・生成された情報、AI エージェント等による処理結果もしくは取引操作に基づく投資判断・注文・取引等に関連して生じたいかなる損害についても、当社の故意または重過失による場合を除き、一切責任を負いません。

APIキー・認証情報の管理

APIキーおよび取引に必要なパスワード等は利用者自身の責任において適切に管理してください。チャット欄や公開リポジトリその他第三者が閲覧可能な環境等へ APIキーや取引パスワード等の認証情報等を入力・掲載しないよう十分ご注意ください。

利用者による認証情報等の管理不備、誤入力、漏えい、第三者利用等により生じたいかなる損害についても、当社の故意または重過失による場合を除き、当社は一切責任を負いません。