bitbank API のデータを使った暗号資産市場分析を、Claude / Cursor / Codex / Antigravity CLI など各種 AI クライアントから簡単に実行できる MCP サーバーです。
- 本ツールは開発段階(ベータ版)です。利用は自己責任でお願いします。
- ご利用の前に必ず
⚠️ 免責事項 をお読みください。 - 本リポジトリは bitbank バグバウンティプログラムの対象範囲外 です。
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として公開されています。
ソースコードのクローンは不要です(開発したい方向けの手順は末尾の開発者向けセクションを参照)。
Claude Desktop が最も多くの方が使う想定の MCP クライアントです。
~/Library/Application Support/Claude/claude_desktop_config.json に設定を追加します。
登録方法は2通りあります。まず 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 の出力 |
インストール方法 |
|---|---|
/opt/homebrew/bin/npx |
Homebrew(Apple Silicon Mac) |
/usr/local/bin/npx |
Homebrew(Intel Mac)または公式インストーラ |
/Users/XXX/.nvm/versions/node/vXX.XX.X/bin/npx |
nvm |
/Users/XXX/.volta/bin/npx |
volta |
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 でも 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
{
"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 mcp add --transport stdio bitbank-lab -- npx -y bitbank-lab-mcp同梱 Skill も一緒に使いたい場合は、セクション 3 の plugin install が便利です。
Cursor と同じ JSON 形式で登録できます。クライアント固有の設定ファイルパスについては各クライアントのドキュメントを参照してください。
通常の利用はセクション 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 | API キーの渡し方 |
|---|---|---|
| Claude Code | .claude-plugin/plugin.json |
✅ GUI で入力: /plugin install 直後に userConfig UI が表示され、OS キーチェーンに保管 |
| Antigravity CLI(旧 Gemini CLI) | gemini-extension.json |
✅ 対話 prompt: settings 配列で対話的に入力、.env に保管 |
| Cursor | .cursor-plugin/plugin.json |
⚙️ シェル環境変数のみ: BITBANK_API_KEY / BITBANK_API_SECRET を環境変数に設定(Cursor は plugin 経由の prompt 未対応) |
| Codex | .codex-plugin/plugin.json |
⚙️ シェル環境変数のみ: BITBANK_API_KEY / BITBANK_API_SECRET を環境変数に設定 |
いずれの 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-pluginsbitbank-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 を使用してください。
AI クライアントにそのまま話しかけます:
BTCの今の市場状況を分析して
ビットコインは買いと売りどちらが優勢?
直近 1 週間でテクニカル的に上向きの仮想通貨を 3 つ教えて
💡 何を聞けばいいかわからない場合: 用意されたプロンプト集 をご覧ください。初心者向け(🔰)から中級者向けまで、9種類の分析プロンプトを用意しています。
🌅 朝のルーティンに: 「おはようレポート」で、寝ている間の相場変動をすばやくキャッチアップできます。
API キーの有無でサーバーが公開する機能が自動的に切り替わります。
| 設定 | ツール数 | プロンプト数 | 使える機能 |
|---|---|---|---|
| キー未設定 | 32(Public のみ) | 8 | 価格取得・テクニカル分析・チャート生成・バックテスト |
| キー設定済み | 32 + 16 = 48 | 8 + 1 = 9 | 上記 + 資産確認・注文・ポートフォリオ分析 |
キー未設定時、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 設定画面 で発行してください。必要最小限の権限のみ付与することを強く推奨します(最小権限の原則)。
| やりたいこと | 必要な権限 |
|---|---|
| 資産確認・ポートフォリオ分析(読み取り専用) | 「参照」のみ ← 最も安全、迷ったらこちら |
| 上記 + AI に発注・キャンセル操作も任せたい | 「参照」+「取引」 |
IP 制限: bitbank 側で API キーに IP 制限を設定できる場合は、可能な限り設定を推奨します。
| カテゴリ | ツール | 説明 | 必要な権限 |
|---|---|---|---|
| 口座情報 | get_my_assets |
保有資産一覧 | 参照 |
| 注文照会 | get_my_orders, get_order, get_orders_info |
注文の照会 | 参照 |
| 約定履歴 | get_my_trade_history |
約定履歴の取得 | 参照 |
| ポートフォリオ | analyze_my_portfolio |
損益分析・パフォーマンス | 参照 |
| 入出金 | get_my_deposit_withdrawal |
入出金履歴 | 参照 |
| 信用取引 | get_margin_status, get_margin_positions, get_margin_trade_history |
証拠金・ポジション・約定履歴 | 参照 |
| 発注 | preview_order → create_order |
2ステップ確認付き発注 | 取引 |
| キャンセル | preview_cancel_order → cancel_order |
2ステップ確認付きキャンセル | 取引 |
| 一括キャンセル | preview_cancel_orders → cancel_orders |
2ステップ確認付き一括キャンセル | 取引 |
取引操作(発注・キャンセル)は preview → execute の2ステップ確認が必須です。preview ツールが発行する確認トークン(HMAC-SHA256、デフォルト60秒有効)なしでは実行できません。
- 「今、BTC は買いですか?」→
analyze_market_signal: 総合スコア + 寄与度・根拠 - 「直近で MACD クロスした銘柄は?」→
detect_macd_cross: スクリーニング結果 - 「ここ 30 日のボラ推移を見たい」→
get_volatility_metrics+render_chart_svg
- MCP クライアント(Claude)では、アーティファクトとして
data.svgを表示するようにお願いしてください。- Claude で LLM がうまくアーティファクトを出力できない場合は、以下のプロンプトを加えるのがおすすめです。
- 「identifier と title を追加して、アーティファクトとして表示して」
- 既定の描画は「ロウソク足のみ」。ボリンジャーバンド等のオーバーレイは明示指定時に追加されます(BBは
--bb-mode=default指定時に ±2σ がデフォルト)。
- Claude で LLM がうまくアーティファクトを出力できない場合は、以下のプロンプトを加えるのがおすすめです。
- プロンプト集(初心者〜中級者向け): docs/prompts-table.md
- ツール一覧と使い分け: docs/tools.md
- Private API ガイド: docs/private-api.md
- 変更履歴: CHANGELOG.md
- 開発者向けガイド(型生成・CI など): CLAUDE.md
- 運用・監視(ログ集計/Docker起動 ほか): docs/ops.md
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 日でもリアルタイムで取得できます。
| 症状 | 原因・対処 |
|---|---|
| Claude Desktop にツールが表示されない | claude_desktop_config.json の JSON 構文が壊れている / Claude Desktop を Cmd+Q(Windows は完全終了)で再起動していない |
| 「サーバーに接続できません」エラー(npx 方式) | Claude Desktop から npx が見つからない可能性。絶対パス方式に切り替える |
spawn npx ENOENT エラー |
which npx の結果が異なるパスを指している。command を正しいパスに書き換える |
| Node.js アップデート後に MCP が動かなくなった | nvm/volta の場合、Node.js バージョンが変わると絶対パスも変わる。which npx を再確認して command を更新するか、npx 方式(npx 名指し)に切り替える |
Cannot find package 'tsx' エラー |
bitbank-lab-mcp の古い版(v0.1.0)でこの問題が発生。npx -y bitbank-lab-mcp@latest で最新版に更新するか、設定を再起動 |
| ツール実行時にタイムアウト | ネットワーク接続を確認 / bitbank API の状態を確認 |
| Private API ツールが表示されない | BITBANK_API_KEY と BITBANK_API_SECRET の両方が設定されているか確認(→ docs/private-api.md) |
| ログを確認したい | env に "LOG_LEVEL": "debug" を追加して再起動 |
| Plugin install で「Marketplace not found」 | /plugin marketplace add bitbankinc/bitbank-lab-mcp を先に実行してから /plugin install bitbank-lab-mcp@bitbank-lab |
このセクションは「自分で 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 cipackage-lock.json 通りに依存をインストールするため、ローカル開発でも npm install ではなく npm ci を推奨します(CI も npm ci を使用)。
ビルドステップは不要です(tsx で TypeScript を直接実行します)。
ローカルの開発版を 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.tsnpx が 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" }
}
}
}開発時のコマンド一覧は CLAUDE.md を参照してください(npm test / npm run lint:fix / npm run gen:types 等)。
バグ報告や機能要望は GitHub Issues からお願いします。Issue テンプレートを用意していますので、用途に合ったものを選択してください。
本ツールは開発段階(ベータ版)です。バグ、不具合、誤動作、または不正確な分析結果を含む可能性があります。
本MCPサーバー / 本CLIツール が提供するデータを AIエージェント等が処理・生成した結果について、正確性、完全性、有用性、最新性を保証するものではありません。AI エージェント等による処理の結果、注文種別、価格、数量その他の取引条件が利用者の意図と異なる形で処理または実行される可能性があります。
本MCPサーバーは情報提供のみを目的として提供されるものであり、投資助言・代理業、投資勧誘、その他金融商品取引法上の行為を目的とするものではありません。
本MCPサーバーは外部API、LLM、第三者サービス等に依拠して提供するものであり、これらの仕様変更、停止、不具合等が生じた場合には、本MCPサーバーが正常に動作しない可能性があります。
本MCPサーバーに実装されている最終注文確認機能、バリデーションその他の安全対策は、誤操作または誤発注等を防止するための補助機能であり、その完全な防止を保証するものではありません。
利用者は、本MCPサーバーにより提供・生成された情報および注文内容等を自身で十分に確認の上、自己の判断と責任において本MCPサーバーを利用し、投資判断、注文実行および取引を行うものとします。
当社は、本MCPサーバーの利用もしくは利用不能、または本MCPサーバーにより提供・生成された情報、AI エージェント等による処理結果もしくは取引操作に基づく投資判断・注文・取引等に関連して生じたいかなる損害についても、当社の故意または重過失による場合を除き、一切責任を負いません。
APIキーおよび取引に必要なパスワード等は利用者自身の責任において適切に管理してください。チャット欄や公開リポジトリその他第三者が閲覧可能な環境等へ APIキーや取引パスワード等の認証情報等を入力・掲載しないよう十分ご注意ください。
利用者による認証情報等の管理不備、誤入力、漏えい、第三者利用等により生じたいかなる損害についても、当社の故意または重過失による場合を除き、当社は一切責任を負いません。