{
"markdown": "# bitbank-lab-mcp\n\n[](https://github.com/bitbankinc/bitbank-lab-mcp/actions/workflows/ci.yml)\n[](LICENSE)\n[](https://www.npmjs.com/package/bitbank-lab-mcp)\n[](https://coderabbit.ai)\n\n> bitbank API のデータを使った暗号資産市場分析を、Claude / Cursor / Codex / Antigravity CLI など各種 AI クライアントから簡単に実行できる MCP サーバーです。\n\n## はじめにお読みください\n\n- 本ツールは**開発段階（ベータ版）**です。利用は**自己責任**でお願いします。\n- ご利用の前に必ず [⚠️ 免責事項](#免責事項) をお読みください。\n- 本リポジトリは **bitbank バグバウンティプログラムの対象範囲外** です。\n\n## 本 MCP サーバーについて\n\nbitbank の公開 API から取得した価格・取引データを、指標計算・統合・可視化用データの整形まで行った上で LLM に渡します（必要に応じてサーバー側で SVG 描画も可能）。生データを渡すだけのサーバーとは異なり、各ツールの description に「いつ使うべきか」「他ツールとの使い分け」を明示しているため、LLM が自律的に適切なツールを選択できます。\n\n姉妹プロジェクトとして、同じ bitbank API に対する真逆のアプローチを提供する **CLI** ([bitbank-lab-cli](https://github.com/bitbankinc/bitbank-lab-cli)) もあります。\n\n- **この MCP サーバー** はサーバー側で計算済みの結論を LLM に渡す\n- **CLI** は生データを高速に取得し、LLM 自身に計算させる\n\n指標のパラメータやロジックを完全にカスタマイズしたい場合は CLI 側を、すぐに使えるテクニカル分析・可視化を求める場合は MCP サーバー側を選んでください。\n\n## 概要\nbitbank の公開 API から価格・板情報・約定履歴・ローソク足データを取得し、以下の分析を実行できます。 \n→ 全ツールの一覧と使い分けは [docs/tools.md](docs/tools.md) を参照。\n\n#### 取得できるデータ\n- リアルタイム価格（ティッカー）\n- 板情報（オーダーブック）\n- 約定履歴（売買方向・時刻）\n- ローソク足（1分足〜月足）\n\n#### 実行できる分析\n- テクニカル指標（SMA/RSI/ボリンジャーバンド/一目均衡表/MACD）\n- フロー分析（買い/売りの勢い・CVD・スパイク検出）\n- ボラティリティ分析（RV/ATR）\n- 板の圧力分析（価格帯ごとの買い/売り圧力）\n- パターン検出（ダブルトップ/ヘッドアンドショルダーズ等）\n- 総合スコア判定（複数指標を統合した強弱判定）\n - 長期パターンの現在地関連検出（detect_patterns: requireCurrentInPattern/currentRelevanceDays）\n\n#### 視覚化\n- Claude.ai の Visualizer で描画するためのコンパクトな整形データを返すツール群\n - `prepare_chart_data`: ローソク足 + 指標の時系列データ\n - `prepare_depth_data`: 板の累積 volume 階段データ\n- ファイル保存・Cursor 等の非 Visualizer 環境向けに SVG/PNG 形式のチャートも生成可能\n - `render_chart_svg` / `render_depth_svg` / `render_candle_pattern_diagram`\n\n## クイックスタート\n\n### 前提条件\n- **Node.js 22 以上**（24 推奨）\n - `node -v` で確認できます\n - [公式サイト](https://nodejs.org/) からインストール\n- npm（Node.js に同梱されています）\n- 対応 OS: macOS / Linux / Windows（WSL 含む）\n- **Claude Desktop** アプリを [Claude 公式サイト](https://claude.com/ja/download) からダウンロードしてください\n\n> 本プロジェクトは npm に [`bitbank-lab-mcp`](https://www.npmjs.com/package/bitbank-lab-mcp) として公開されています。 \n> **ソースコードのクローンは不要**です（開発したい方向けの手順は[末尾の開発者向けセクション](#開発者向けソースから起動)を参照）。\n\n### 1. Claude Desktop に登録（推奨）\n\nClaude Desktop が最も多くの方が使う想定の MCP クライアントです。 \n`~/Library/Application Support/Claude/claude_desktop_config.json` に設定を追加します。\n\n登録方法は2通りあります。**まず npx 方式を試し、動かない場合に絶対パス方式をお試しください。**\n\n#### npx 方式（推奨）\n\nNode.js のバージョンアップで設定を書き換える必要がないため、こちらを推奨します。 \nnvm/volta などのバージョン管理ツールをお使いの方には特におすすめです。\n\n用途に応じて **A〜C の 3 段階**から選びます。\n\n**A. Public データのみ:**\n\n価格・板・ローソク足などの公開市場データの取得と分析。API キー不要。\n\n```json\n{\n \"mcpServers\": {\n \"bitbank-lab\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"bitbank-lab-mcp\"]\n }\n }\n}\n```\n\n**B. Private データ参照系（要 API キー）:**\n\n資産残高・約定履歴・注文照会・ポートフォリオ分析などの読み取り専用。発注はできません。\n\n```json\n{\n \"mcpServers\": {\n \"bitbank-lab\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"bitbank-lab-mcp\"],\n \"env\": {\n \"BITBANK_API_KEY\": \"your_api_key\",\n \"BITBANK_API_SECRET\": \"your_api_secret\"\n }\n }\n }\n}\n```\n\n> ✅ **bitbank API の権限は「参照」のみ設定することを推奨**\n\n**C. 取引注文・注文キャンセル実行（要 API キー）:**\n\nB に加えて、対応ホスト上での発注・注文キャンセルまで実行。実行前に必ず確認ステップ（preview → ユーザーの明示確認）が入ります。\n\n```json\n{\n \"mcpServers\": {\n \"bitbank-lab\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"bitbank-lab-mcp\"],\n \"env\": {\n \"BITBANK_API_KEY\": \"your_api_key\",\n \"BITBANK_API_SECRET\": \"your_api_secret\"\n }\n }\n }\n}\n```\n\n> ✅ **bitbank API の権限は「参照」および「取引」のみ設定することを推奨**\n>\n> ※ **「出金」権限は有効化しないことを強く推奨します**。本サーバーは出金系ツール未実装のため不要です。\n\n発注・取消の実行には**ユーザーの明示確認が必須**です。確認トークンは `content` / `structuredContent` に載らないため、LLM が preview 応答から直接 execute することはできません。旧 `BITBANK_TRUST_HOST_APPROVAL` オプトイン（iframe に token を `structuredContent` で載せる妥協モード）はセキュリティ上撤去済みで、設定しても無視されます。\n\n確認の経路はクライアントによって変わります。\n\n| クライアント | 実行経路 |\n|---|---|\n| elicitation / MRTR 対応 | ネイティブ確認ダイアログで完結（**第一選択**。追加設定不要） |\n| MCP Apps UI 対応（Claude Desktop 等） | `BITBANK_MCP_APPS_EXECUTE=1` を設定した場合のみ、確認カードのボタンで実行（**既定は無効**） |\n| どちらも非対応 | プレビューのみ。実行は bitbank アプリ/ウェブで |\n\n\n⚠️ BITBANK_MCP_APPS_EXECUTE=1 を設定する前に読んでください
\n\nこのオプションは、確認トークンをツール結果の `_meta` にのみ載せて iframe へ渡し、確認カードのボタンからの実行を許可します。安全性は「**ホストが `_meta` をモデル（LLM）に渡さない**」という前提に依存します。\n\n* **仕様上の保証ではありません。** MCP Apps 仕様の該当記述は \"Best Practices\" の箇条書きで、MUST / SHOULD を伴いません。適合要件ではなく意図の説明です\n* **ホストのアップデートで壊れても、サーバー側では検知できません。** ホストが `_meta` をモデルコンテキストに含めるようになった瞬間に前提は崩れますが、その変化はサーバーから観測できません。**壊れ方は静かです**\n* この領域は実装が流動的です（`structuredContent` の喪失回帰など、関連トラッカーに 2026-05〜08 の issue が複数）\n* **クライアントの申告は検証できません。** トークンを渡す条件は「クライアントが MCP Apps UI 対応を宣言していること」ですが、これはクライアント側の自己申告で、サーバーは真偽を判定できません。確認カードを描画しないクライアントでも、宣言さえすればトークンを取得できます。**信頼できるクライアントでのみ有効にしてください**\n* **API キーの置き場所で意味が変わります。** キーをクライアント側（`claude_desktop_config.json` の `env` 等）に設定している場合、クライアントは既にキーを保持しているため、このフラグによる追加のリスクはありません。**サーバー側の `.env` に置く構成では、クライアントに本来無い実行権限を与えることになります**。この構成での有効化は推奨しません\n\n万一トークンが漏れた場合でも、被害は **「直前にプレビューした注文 1 件（一括取消ならプレビュー済みの注文 ID 集合 1 セット）が、60 秒以内に 1 回だけ実行される」** に限定されます。トークンは注文内容に HMAC で束縛されており、攻撃者が金額・数量・ペア・方向を選ぶことはできません。\n\n**以上を理解したうえで有効化してください。既定では無効です。** 詳細は [ADR-0007](docs/adr/0007-hitl-confirmation-token-delivery.md)。\n\n \n\n詳細: [ADR-0007](docs/adr/0007-hitl-confirmation-token-delivery.md) / [Private API ガイド](docs/private-api.md)。\n\nB / C の API キーは [bitbank 設定画面](https://app.bitbank.cc/account/api) で発行し、**必要最小限の権限のみ**を付与、可能なら **IP 制限**も設定してください（最小権限の原則）。\n\n詳細: [Private API ガイド](docs/private-api.md)。\n\n#### 絶対パス方式（フォールバック）\n\nnpx 方式で「サーバーに接続できません」エラーが出る場合、Claude Desktop から `npx` コマンドが見つけられていない可能性があります。 \nその場合は、`npx` の絶対パスを指定してください。\n\nまずターミナルで自分の環境の `npx` パスを確認します：\n\n```bash\nwhich npx\n```\n\n出力例と対応するインストール方法：\n\n| `which npx` の出力 | インストール方法 |\n|---|---|\n| `/opt/homebrew/bin/npx` | Homebrew（Apple Silicon Mac） |\n| `/usr/local/bin/npx` | Homebrew（Intel Mac）または公式インストーラ |\n| `/Users/XXX/.nvm/versions/node/vXX.XX.X/bin/npx` | nvm |\n| `/Users/XXX/.volta/bin/npx` | volta |\n\n`which npx` の結果を `command` に指定：\n\n```json\n{\n \"mcpServers\": {\n \"bitbank-lab\": {\n \"command\": \"\",\n \"args\": [\"-y\", \"bitbank-lab-mcp\"]\n }\n }\n}\n```\n\n> ⚠️ **nvm/volta ユーザーへの注意**: この方式では Node.js をバージョンアップするたびに `command` のパスの書き換えが必要です（例: `v24.0.0` → `v24.1.0`）。アップデート後に `which npx` を再確認してください。\n\n#### Windows の場合\n\nWindows でも npx 方式がそのまま使えます：\n\n```json\n{\n \"mcpServers\": {\n \"bitbank-lab\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"bitbank-lab-mcp\"]\n }\n }\n}\n```\n\n設定ファイルの場所: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n`npx` が見つからない場合は `where npx`（Windows 版の `which`）で絶対パスを確認して指定してください。\n\n#### 表示名のカスタマイズ\n\nClaude Desktop の UI に表示される名前は `claude_desktop_config.json` のキー名で決まります：\n\n```json\n{\n \"mcpServers\": {\n \"bitbank-lab-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"bitbank-lab-mcp\"]\n }\n }\n}\n```\n\n> ⚠️ `bitbank-lab-mcp` のような ASCII（英数字）の名前を推奨します。環境によって、日本語などの非 ASCII 名だと Chat でツールが見つからない事例があります。\n\n#### 共通の注意事項\n\n- 追加後、Claude Desktop を `Cmd+Q`（Windows は完全終了）で再起動してください\n- ⚠️ macOS で `claude_desktop_config.json` が見つからない場合は、ホームディレクトリ直下から開いてください\n\n設定ファイルの場所：\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n### 2. その他の MCP クライアント（手動 `.json` 編集）\n\n#### Cursor（`.cursor/mcp.json`）\n\n```json\n{\n \"mcpServers\": {\n \"bitbank-lab\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"bitbank-lab-mcp\"],\n \"env\": {\n \"BITBANK_API_KEY\": \"your_api_key\",\n \"BITBANK_API_SECRET\": \"your_api_secret\"\n }\n }\n }\n}\n```\n\nAPI キーが不要な場合は `env` ブロックごと削除して OK。セクション 1 の A〜C と同様に、取引実行まで使う場合は確認フローに対応したクライアントが必要です（旧 `BITBANK_TRUST_HOST_APPROVAL` は不要・無効です）。\n\n#### Claude Code（CLI から登録する場合）\n\n```bash\nclaude mcp add --transport stdio bitbank-lab -- npx -y bitbank-lab-mcp\n```\n\n同梱 Skill も一緒に使いたい場合は、[セクション 3](#3-オプションplugin-として-install同梱-skill-を使う) の plugin install が便利です。\n\n#### Windsurf / その他の汎用 MCP クライアント\n\nCursor と同じ JSON 形式で登録できます。クライアント固有の設定ファイルパスについては各クライアントのドキュメントを参照してください。\n\n### 3. （オプション）Plugin として install（同梱 Skill を使う）\n\n通常の利用はセクション 1〜2 の登録だけで完結します。Plugin install は、**Claude Code などの AI コーディングツールで、MCP サーバーに加えて同梱 Skill（`skills/` 配下）も使いたい方向け**のオプションです。\n\n- Plugin として install すると、MCP ツールと同時に同梱 Skill（例: `investment-onboarding`）が有効化されます。今後 Skill を追加した場合も、plugin のアップデートでまとめて届きます。\n- Skill を自作してワークフローをカスタマイズしたい方は、[`skills/INDEX.md`](skills/INDEX.md) の構成が参考になります。\n- **Claude Desktop は plugin / Skill の読み込みに未対応**です。Claude Desktop で使う場合は[セクション 1](#1-claude-desktop-に登録推奨) の方法で登録してください（MCP ツールの機能は同じで、Skill が使えるかどうかだけの違いです）。\n\n| クライアント | manifest | API キーの渡し方 |\n|---|---|---|\n| Claude Code | `.claude-plugin/plugin.json` | ✅ **GUI で入力**: `/plugin install` 直後に `userConfig` UI が表示され、OS キーチェーンに保管 |\n| Antigravity CLI（旧 Gemini CLI） | `gemini-extension.json` | ✅ **対話 prompt**: `settings` 配列で対話的に入力、`.env` に保管 |\n| Cursor | `.cursor-plugin/plugin.json` | ⚙️ **シェル環境変数のみ**: `BITBANK_API_KEY` / `BITBANK_API_SECRET` を環境変数に設定（Cursor は plugin 経由の prompt 未対応） |\n| Codex | `.codex-plugin/plugin.json` | ⚙️ **シェル環境変数のみ**: `BITBANK_API_KEY` / `BITBANK_API_SECRET` を環境変数に設定 |\n\n> いずれの manifest も npm registry の [`bitbank-lab-mcp`](https://www.npmjs.com/package/bitbank-lab-mcp) を `npx -y` 経由で起動します。\n>\n> Gemini CLI は 2026-06-18 に個人アカウント向け提供を終了し、Antigravity CLI（`agy`）に移行しました。Antigravity CLI は旧 Gemini CLI 拡張（`gemini-extension.json`）を後方互換で読み込みます（`agy plugin import gemini` でネイティブ plugin へ変換も可能）。\n\n**Claude Code の例**:\n\n```bash\n# 1. このリポジトリを marketplace として登録（初回のみ）\n/plugin marketplace add bitbankinc/bitbank-lab-mcp\n\n# 2. plugin を install\n/plugin install bitbank-lab-mcp@bitbank-lab\n\n# 3. plugin を有効化\n/reload-plugins\n```\n\n`bitbank-lab` はこのリポが提供する marketplace 名（`.claude-plugin/marketplace.json` の `name` フィールド）、`bitbank-lab-mcp` は plugin 名です。\n\n実行後、bitbank API key / API secret の入力 UI が表示されます。**Public ツールだけで使う場合は両方とも空欄で OK** — Private API ツールは API キーを入力したときだけ自動的に有効化されます。\n\n> API キーを後から追加・変更したい場合は `/plugin` から該当 plugin の設定を開き、`api_key` / `api_secret` を更新してください。Claude Code では `sensitive: true` のため OS のキーチェーンに保管されます。\n\n**Cursor / Codex の場合（環境変数経由）**:\n\n`/plugin install` 実行後、シェルで以下のように環境変数を設定してから Cursor / Codex を起動してください（Public ツールだけ使う場合は不要）:\n\n```bash\nexport BITBANK_API_KEY=\"your_api_key\"\nexport BITBANK_API_SECRET=\"your_api_secret\"\n```\n\nmacOS / Linux では `~/.zshrc` や `~/.bashrc` に書いておくと永続化されます。Windows は環境変数の管理画面 or `setx` を使用してください。\n\n### 4. 使ってみる\nAI クライアントにそのまま話しかけます:\n```\nBTCの今の市場状況を分析して\nビットコインは買いと売りどちらが優勢？\n直近 1 週間でテクニカル的に上向きの仮想通貨を 3 つ教えて\n```\n\n💡 **何を聞けばいいかわからない場合**: [用意されたプロンプト集](docs/prompts-table.md) をご覧ください。初心者向け（🔰）から中級者向けまで、9種類の分析プロンプトを用意しています。\n\n🌅 **朝のルーティンに**: 「おはようレポート」で、寝ている間の相場変動をすばやくキャッチアップできます。\n\n\n## Private API（取引機能）\n\nAPI キーの有無でサーバーが公開する機能が自動的に切り替わります。\n\n| 設定 | ツール数 | プロンプト数 | 使える機能 |\n|------|---------|------------|-----------|\n| キー未設定 | 33（Public のみ） | 8 | 価格取得・テクニカル分析・チャート生成・バックテスト |\n| キー設定済み | 33 + 16 = **49** | 8 + 1 = **9** | 上記 + 資産確認・注文・ポートフォリオ分析 |\n\nキー未設定時、Private ツール・プロンプトは MCP クライアントに一切表示されません（エラーではなく、そもそも登録されません）。公開データの取得・分析だけなら設定不要で、そのまま使えます。\n\n### 環境変数の設定方法\n\n**ターミナルから起動する場合:**\n```bash\nexport BITBANK_API_KEY=\"your_api_key\"\nexport BITBANK_API_SECRET=\"your_api_secret\"\n```\n\n**Plugin install を使った場合** — `/plugin` から該当 plugin の設定を開き、`api_key` / `api_secret` を入力すれば完了です（手動編集は不要）。\n\n**Claude Desktop で手動設定している場合** — `claude_desktop_config.json` の `env` に追加（[セクション 1](#1-claude-desktop-に登録推奨) で設定した npx 方式／絶対パス方式のいずれかに、以下のように `BITBANK_API_KEY` と `BITBANK_API_SECRET` を追加するだけです）:\n```json\n{\n \"mcpServers\": {\n \"bitbank-lab\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"bitbank-lab-mcp\"],\n \"env\": {\n \"BITBANK_API_KEY\": \"your_api_key\",\n \"BITBANK_API_SECRET\": \"your_api_secret\"\n }\n }\n }\n}\n```\n\nAPI キーは [bitbank 設定画面](https://app.bitbank.cc/account/api) で発行してください。**必要最小限の権限のみ付与する**ことを強く推奨します（最小権限の原則）。\n\n| やりたいこと | 必要な権限 |\n|---|---|\n| 資産確認・ポートフォリオ分析（読み取り専用） | **「参照」のみ** ← 最も安全、迷ったらこちら |\n| 上記 + AI に発注・キャンセル操作も任せたい | 「参照」+「取引」 |\n\n⚠️ **「出金」権限は絶対に有効化しないでください**。本 MCP サーバーは出金系ツールを実装していないため、この権限を付ける必要は一切ありません。漏洩時の資産流出を避けるためです。\n\n**IP 制限**: bitbank 側で API キーに IP 制限を設定できる場合は、可能な限り設定を推奨します。\n\n| カテゴリ | ツール | 説明 | 必要な権限 |\n|---|---|---|---|\n| 口座情報 | `get_my_assets` | 保有資産一覧 | 参照 |\n| 注文照会 | `get_my_orders`, `get_order`, `get_orders_info` | 注文の照会 | 参照 |\n| 約定履歴 | `get_my_trade_history` | 約定履歴の取得 | 参照 |\n| ポートフォリオ | `analyze_my_portfolio` | 損益分析・パフォーマンス | 参照 |\n| 入出金 | `get_my_deposit_withdrawal` | 入出金履歴 | 参照 |\n| 信用取引 | `get_margin_status`, `get_margin_positions`, `get_margin_trade_history` | 証拠金・ポジション・約定履歴 | 参照 |\n| 発注 | `preview_order`（→ ユーザー確認） | ユーザー明示確認後に発注 | 取引 |\n| キャンセル | `preview_cancel_order`（→ ユーザー確認） | ユーザー明示確認後にキャンセル | 取引 |\n| 一括キャンセル | `preview_cancel_orders`（→ ユーザー確認） | ユーザー明示確認後に一括キャンセル | 取引 |\n\n取引操作（発注・キャンセル）は **preview → ユーザーの明示確認**が必須です。確認トークンは `content` / `structuredContent` に載らず、`create_order` / `cancel_order` / `cancel_orders` を MCP `tools/call` から直接呼んでもサーバー側で拒否されます。\n\n詳細: [docs/private-api.md](docs/private-api.md)\n\n## 使用例（会話の型）\n- 「今、BTC は買いですか？」→ `analyze_market_signal`: 総合スコア + 寄与度・根拠\n- 「直近で MACD クロスした銘柄は？」→ `detect_macd_cross`: スクリーニング結果\n- 「ここ 30 日のボラ推移を見たい」→ `get_volatility_metrics` + `render_chart_svg`\n\n## チャート表示（SVG）\n- MCP クライアント（Claude）では、アーティファクトとして `data.svg` を表示するようにお願いしてください。\n - Claude で LLM がうまくアーティファクトを出力できない場合は、以下のプロンプトを加えるのがおすすめです。\n - 「identifier と title を追加して、アーティファクトとして表示して」 \n - 既定の描画は「ロウソク足のみ」。ボリンジャーバンド等のオーバーレイは明示指定時に追加されます（BBは `--bb-mode=default` 指定時に ±2σ がデフォルト）。\n\n## 詳細ドキュメント\n- プロンプト集（初心者〜中級者向け）: [docs/prompts-table.md](docs/prompts-table.md)\n- ツール一覧と使い分け: [docs/tools.md](docs/tools.md)\n- Private API ガイド: [docs/private-api.md](docs/private-api.md)\n- 変更履歴: [CHANGELOG.md](CHANGELOG.md)\n- 開発者向けガイド（型生成・CI など）: [CLAUDE.md](CLAUDE.md)\n- 運用・監視（ログ集計／Docker起動 ほか）: [docs/ops.md](docs/ops.md)\n\n## よくある質問（FAQ）\n**Q. 何を聞けばいいかわからない** [プロンプト集](docs/prompts-table.md) を参照してください。初心者向け🔰から中級者向けまで9種類の分析プロンプトを用意しています。\n\n**Q. Docker は必須？** いいえ。Node 18+ でローカル実行できます（最短は Claude Desktop 登録）。\n\n**Q. API キーは必要？** 公開データの取得・分析には不要です。自分の資産確認や注文操作（Private API）を使う場合は [Private API ガイド](docs/private-api.md) を参照してください。\n\n**Q. どのツールを使えばよい？** まず `analyze_market_signal` で全体を把握 → 必要に応じて各専門ツールへ。\n\n**Q. 対応銘柄は固定？** 固定ではありません。上流の公開 API が返す銘柄に自動追随します（追加/廃止も自動反映）。参考: [bitbank 公開API仕様](https://github.com/bitbankinc/bitbank-api-docs/blob/master/public-api.md)\n\n**Q. MCP Inspector でも試せる？** はい。次で実行できます（npm 公開版に対する動作確認）。\n```bash\nnpx @modelcontextprotocol/inspector -- npx -y bitbank-lab-mcp\n```\nソースコードから動かす場合は `npx @modelcontextprotocol/inspector -- tsx src/server.ts`（[開発者向け](#開発者向けソースから起動) を参照）。\n\n**Q. 当日の約定（フロー）データが少ない・古い時間帯が取れない** bitbank 側の仕様です。約定履歴の日付アーカイブ（`/transactions/{YYYYMMDD}`）は **UTC 暦日単位**で、当該 UTC 日の完了後（日本時間 9:00 以降、さらに公開遅延あり）にのみ公開されます。進行中の UTC 日の約定は直近約 60 件（latest）しか取得できないため、`get_flow_metrics` 等では当日区間のカバレッジが限定的になります（結果に warning として明示されます）。ローソク足（`get_candles`）は進行中の UTC 日でもリアルタイムで取得できます。\n\n## トラブルシューティング\n\n| 症状 | 原因・対処 |\n|------|-----------|\n| Claude Desktop にツールが表示されない | `claude_desktop_config.json` の JSON 構文が壊れている / Claude Desktop を `Cmd+Q`（Windows は完全終了）で再起動していない |\n| 「サーバーに接続できません」エラー（npx 方式） | Claude Desktop から `npx` が見つからない可能性。[絶対パス方式](#絶対パス方式フォールバック)に切り替える |\n| `spawn npx ENOENT` エラー | `which npx` の結果が異なるパスを指している。`command` を正しいパスに書き換える |\n| Node.js アップデート後に MCP が動かなくなった | nvm/volta の場合、Node.js バージョンが変わると絶対パスも変わる。`which npx` を再確認して `command` を更新するか、npx 方式（`npx` 名指し）に切り替える |\n| `Cannot find package 'tsx'` エラー | `bitbank-lab-mcp` の古い版（v0.1.0）でこの問題が発生。`npx -y bitbank-lab-mcp@latest` で最新版に更新するか、設定を再起動 |\n| ツール実行時にタイムアウト | ネットワーク接続を確認 / [bitbank API の状態](https://status.bitbank.cc/)を確認 |\n| Private API ツールが表示されない | `BITBANK_API_KEY` と `BITBANK_API_SECRET` の両方が設定されているか確認（→ [docs/private-api.md](docs/private-api.md)） |\n| ログを確認したい | `env` に `\"LOG_LEVEL\": \"debug\"` を追加して再起動 |\n| Plugin install で「Marketplace not found」 | `/plugin marketplace add bitbankinc/bitbank-lab-mcp` を先に実行してから `/plugin install bitbank-lab-mcp@bitbank-lab` |\n\n---\n\n## 開発者向け（ソースから起動）\n\nこのセクションは「自分で MCP サーバーをいじりたい」「PR を送りたい」という開発者向けです。**通常の利用者は[セクション 1](#1-claude-desktop-に登録推奨) の `npx -y bitbank-lab-mcp` 方式で OK** です（こちらは clone 不要）。\n\n### セットアップ\n\n```bash\ngit clone https://github.com/bitbankinc/bitbank-lab-mcp.git\ncd bitbank-lab-mcp\nnpm ci\n```\n\n`package-lock.json` 通りに依存をインストールするため、ローカル開発でも `npm install` ではなく `npm ci` を推奨します（CI も `npm ci` を使用）。\n\nビルドステップは不要です（tsx で TypeScript を直接実行します）。\n\n### STDIO モード（Claude Desktop / Claude Code 向け）\n\nローカルの開発版を Claude Desktop から使いたい場合、`claude_desktop_config.json` に絶対パス指定で登録します：\n\n```json\n{\n \"mcpServers\": {\n \"bitbank-dev\": {\n \"command\": \"npx\",\n \"args\": [\"tsx\", \"/ABS/PATH/to/src/server.ts\"],\n \"workingDirectory\": \"/ABS/PATH/to/project\",\n \"env\": { \"LOG_LEVEL\": \"debug\", \"NO_COLOR\": \"1\" }\n }\n }\n}\n```\n\n`/ABS/PATH/to/` を実際のクローン先パス（`pwd` で確認）に置き換えてください。**npm 公開版（`bitbank-lab`）と区別するため、サーバー名は `bitbank-dev` 等にしておくと両立できます**。\n\nInspector で動作確認する場合:\n```bash\nnpx @modelcontextprotocol/inspector -- tsx src/server.ts\n```\n\n### Windows でローカル開発する場合\n\n`npx` が PATH 解決できない環境では、`node` の絶対パスと `tsx` の CLI を直接指定します：\n\n```json\n{\n \"mcpServers\": {\n \"bitbank-dev\": {\n \"command\": \"node\",\n \"args\": [\n \"C:\\\\Users\\\\\\\\bitbank-lab-mcp\\\\node_modules\\\\tsx\\\\dist\\\\cli.mjs\",\n \"C:\\\\Users\\\\\\\\bitbank-lab-mcp\\\\src\\\\server.ts\"\n ],\n \"workingDirectory\": \"C:\\\\Users\\\\\\\\bitbank-lab-mcp\",\n \"env\": { \"LOG_LEVEL\": \"debug\", \"NO_COLOR\": \"1\" }\n }\n }\n}\n```\n\n### CI / 型生成 / リンター\n\n開発時のコマンド一覧は [CLAUDE.md](CLAUDE.md) を参照してください（`npm test` / `npm run lint:fix` / `npm run gen:types` 等）。\n\n## フィードバック・バグ報告\n\nバグ報告や機能要望は [GitHub Issues](https://github.com/bitbankinc/bitbank-lab-mcp/issues) からお願いします。Issue テンプレートを用意していますので、用途に合ったものを選択してください。\n\n## 免責事項\n\n### 開発段階について\n\n本ツールは開発段階（ベータ版）です。バグ、不具合、誤動作、または不正確な分析結果を含む可能性があります。\n\n### AI エージェントによる処理結果について\n\n本MCPサーバー / 本CLIツール が提供するデータを AIエージェント等が処理・生成した結果について、正確性、完全性、有用性、最新性を保証するものではありません。AI エージェント等による処理の結果、注文種別、価格、数量その他の取引条件が利用者の意図と異なる形で処理または実行される可能性があります。\n\n### 金融商品取引法上の位置づけ\n\n本MCPサーバーは情報提供のみを目的として提供されるものであり、投資助言・代理業、投資勧誘、その他金融商品取引法上の行為を目的とするものではありません。\n\n### 外部サービスへの依拠\n\n本MCPサーバーは外部API、LLM、第三者サービス等に依拠して提供するものであり、これらの仕様変更、停止、不具合等が生じた場合には、本MCPサーバーが正常に動作しない可能性があります。\n\n### 安全対策の補助性\n\n本MCPサーバーに実装されている最終注文確認機能、バリデーションその他の安全対策は、誤操作または誤発注等を防止するための補助機能であり、その完全な防止を保証するものではありません。\n\n### 利用者の責任\n\n利用者は、本MCPサーバーにより提供・生成された情報および注文内容等を自身で十分に確認の上、自己の判断と責任において本MCPサーバーを利用し、投資判断、注文実行および取引を行うものとします。\n\n### 損害の免責\n\n当社は、本MCPサーバーの利用もしくは利用不能、または本MCPサーバーにより提供・生成された情報、AI エージェント等による処理結果もしくは取引操作に基づく投資判断・注文・取引等に関連して生じたいかなる損害についても、当社の故意または重過失による場合を除き、一切責任を負いません。\n\n### APIキー・認証情報の管理\n\nAPIキーおよび取引に必要なパスワード等は利用者自身の責任において適切に管理してください。チャット欄や公開リポジトリその他第三者が閲覧可能な環境等へ APIキーや取引パスワード等の認証情報等を入力・掲載しないよう十分ご注意ください。\n\n利用者による認証情報等の管理不備、誤入力、漏えい、第三者利用等により生じたいかなる損害についても、当社の故意または重過失による場合を除き、当社は一切責任を負いません。\n",
"bytes": 18979,
"sha": "b9ab6218a94e75e56157363159795dd2045074d0ce6fce6e1ec7f4810f04afb9",
"repo_slug": "bitbankinc/bitbank-lab-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_bitbankinc_bitbank_lab_mcp_9bcc02ca/readme"
}