bitbank-lab-mcp-legacy

# bitbank-lab-mcp [](https://github.com/bitbankinc/bitbank-lab-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://www.npmjs.com/package/bitbank-lab-mcp) [](https://coderabbit.ai) > An MCP server that enables easy execution of cryptocurrency market analysis using bitbank API data from various AI clients such as Claude, Cursor, Codex, and Antigravity CLI. ## Getting Started - This tool is in **development stage (beta version)**. Use at your own risk. - Please read the [Disclaimer](#免責事項) before using. - This repository is **not covered by the bitbank bug bounty program**. ## About This MCP Server This server retrieves price, trading data, and other information from bitbank's public API, performs indicator calculations, integrates and visualizes the data, and passes it to the LLM. Unlike servers that only pass raw data, this server provides clear descriptions of when to use each tool and how to use them with other tools, allowing the LLM to autonomously select the appropriate tool. As a sister project, there is also a **CLI** ([bitbank-lab-cli](https://github.com/bitbankinc/bitbank-lab-cli)) that provides a completely opposite approach to the same bitbank API. - **This MCP server** passes conclusions calculated on the server side to the LLM - **CLI** quickly retrieves raw data and lets the LLM calculate it itself If you want to completely customize indicator parameters and logic, use the CLI side. If you want technical analysis and visualization that can be used immediately, use the MCP server side. ## Overview The server can retrieve price, order book information, trade history, and candlestick data from bitbank's public API and execute the following analysis. → See [docs/tools.md](docs/tools.md) for a list of all tools and how to use them. #### Available Data - Real-time price (ticker) - Order book information (order book) - Trade history (buy/sell direction, time) - Candlestick data (1-minute to monthly) #### Available Analysis - Technical indicators (SMA/RSI/Bollinger Bands/Ichimoku Cloud/MACD) - Flow analysis (buy/sell momentum, CVD, spike detection) - Volatility analysis (RV/ATR) - Order book pressure analysis (buy/sell pressure by price range) - Pattern detection (double top, head and shoulders, etc.) - Overall score judgment (strong/weak judgment integrating multiple indicators) - Long-term pattern current location-related detection (detect_patterns: requireCurrentInPattern/currentRelevanceDays) #### Visualization - A set of tools that return compact formatted data for drawing with Claude.ai's Visualizer - `prepare_chart_data`: Candlestick + indicator time series data - `prepare_depth_data`: Order book cumulative volume step data - SVG/PNG format charts can also be generated for file saving and non-Visualizer environments - `render_chart_svg` / `render_depth_svg` / `render_candle_pattern_diagram` ## Quick Start ### Prerequisites - **Node.js 22 or higher** (24 recommended) - Check with `node -v` - Install from [official website](https://nodejs.org/) - npm (bundled with Node.js) - Supported OS: macOS / Linux / Windows (including WSL) - Download **Claude Desktop** app from [Claude official website](https://claude.com/ja/download) > This project is published on npm as [`bitbank-lab-mcp`](https://www.npmjs.com/package/bitbank-lab-mcp). > **No need to clone the source code** (see [Developer section](#developer) for development). ### 1. Register with Claude Desktop (recommended) Claude Desktop is the most commonly used MCP client. Add settings to `~/Library/Application Support/Claude/claude_desktop_config.json`. There are two ways to register. Try **npx method first, and then try absolute path method if it doesn't work**. #### npx Method (recommended) This method is recommended because you don't need to rewrite settings when Node.js is updated. Choose from **three levels A-C**. **A. Public data only:** Retrieve and analyze public market data such as price, order book, and candlestick data. No API key required. ```json { "mcpServers": { "bitbank-lab": { "command": "npx", "args": ["-y", "bitbank-lab-mcp"] } } } ``` **B. Private data reference (API key required):** Read-only access to asset balance, trade history, order inquiry, and portfolio analysis. No ordering possible. ```json { "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 permissions should be set to "read-only"** **C. Trade order and cancel execution (API key required):** In addition to B, execute trade orders and cancellations from AI. A confirmation step (preview → execute) is required before execution. ```json { "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 permissions should be set to "read-only" and "trade" only** > > ※ **Do not enable "withdrawal" permission**. This server does not implement withdrawal tools. `BITBANK_TRUST_HOST_APPROVAL` (value is string `"1"` only) is an opt-in that allows Claude Desktop to execute orders/cancellations from the confirmation button. If enabled, the confirmation token can be seen by LLM, but the token is **valid for one previewed order only, expires in 60 seconds, and is disposable**. The host's approval dialog is required as a final gate before execution. Details: [ADR-0007](docs/adr/0007-hitl-confirmation-token-delivery.md) / [Private API guide](docs/private-api.md). B / C API keys are issued on [bitbank settings page](https://app.bitbank.cc/account/api) and grant **minimum necessary permissions only**. If possible, set **IP restrictions** (principle of least privilege). Details: [Private API guide](docs/private-api.md). #### Absolute Path Method (fallback) If "Cannot connect to server" error occurs with npx method, Claude Desktop may not be able to find `npx` command. Check the absolute path of `npx` in terminal: ```bash which npx ``` Output example and installation method: | `which npx` output | Installation method | |---|---| | `/opt/homebrew/bin/npx` | Homebrew (Apple Silicon Mac) | | `/usr/local/bin/npx` | Homebrew (Intel Mac) or official installer | | `/Users/XXX/.nvm/versions/node/vXX.XX.X/bin/npx` | nvm | | `/Users/XXX/.volta/bin/npx` | volta | Specify the absolute path of `npx` in `command`: ```json { "mcpServers": { "bitbank-lab": { "command": "<absolute path of npx>", "args": ["-y", "bitbank-lab-mcp"] } } } ``` > ⚠️ **Attention for nvm/volta users**: This method requires rewriting the path of `command` every time Node.js is updated (e.g., `v24.0.0` → `v24.1.0`). Reconfirm `which npx` after update. #### Windows npx method works on Windows: ```json { "mcpServers": { "bitbank-lab": { "command": "npx", "args": ["-y", "bitbank-lab-mcp"] } } } ``` Settings file location: `%APPDATA%\Claude\claude_desktop_config.json` If `npx` is not found, check the absolute path with `where npx` (Windows version of `which`) and specify it. #### Customize Display Name The name displayed on Claude Desktop's UI is determined by the key name in `claude_desktop_config.json`: ```json { "mcpServers": { "bitbank-lab-mcp": { "command": "npx", "args": ["-y", "bitbank-lab-mcp"] } } } ``` > ⚠️ Recommend **ASCII name** (e.g., `bitbank-lab-mcp`). Some environments may not find tools with non-ASCII names. #### Common Notes - Restart Claude Desktop with `Cmd+Q` (Windows: complete exit) after adding settings - ⚠️ On macOS, if `claude_desktop_config.json` is not found, open from the home directory Settings file locations: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` ### 2. Other MCP Clients (manual `.json` editing) #### Cursor (`.cursor/mcp.json`) ```json { "mcpServers": { "bitbank-lab": { "command": "npx", "args": ["-y", "bitbank-lab-mcp"], "env": { "BITBANK_API_KEY": "your_api_key", "BITBANK_API_SECRET": "your_api_secret" } } } } ``` If no API key is required, remove the `env` block. #### Claude Code (registering from CLI) ```bash claude mcp add --transport stdio bitbank-lab -- npx -y bitbank-lab-mcp ``` If you want to use the bundled Skill, see [Section 3](#3-optional-install-bundled-skill). #### Windsurf / Other generic MCP clients Register with the same JSON format as Cursor. Refer to each client's documentation for client-specific settings file paths. ### 3. (Optional) Install Bundled Skill Normal usage is complete with registration in Sections 1-2. Plugin install is for **users who want to use the bundled Skill (in `skills/` directory) in addition to the MCP server**. - Installing the plugin enables the bundled Skill (e.g., `investment-onboarding`) along with the MCP tool. Future Skill additions will be delivered through plugin updates. - For users who want to customize workflows by creating their own Skills, refer to [`skills/INDEX.md`](skills/INDEX.md). | Client | manifest | API key passing method | |---|---|---| | Claude Code | `.claude-plugin/plugin.json` | ✅ **GUI input**: `/plugin install` displays `userConfig` UI, stored in OS keychain | | Antigravity CLI (former Gemini CLI) | `gemini-extension.json` | ✅ **Interactive prompt**: input interactively in `settings` array, stored in `.env` | | Cursor | `.cursor-plugin/plugin.json` | ⚙️ **Shell environment variables only**: set `BITBANK_API_KEY` / `BITBANK_API_SECRET` as environment variables (Cursor does not support interactive prompt) | | Codex | `.codex-plugin/plugin.json` | ⚙️ **Shell environment variables only**: set `BITBANK_API_KEY` / `BITBANK_API_SECRET` as environment variables | > All manifests use npm registry's [`bitbank-lab-mcp`](https://www.npmjs.com/package/bitbank-lab-mcp) launched via `npx -y`. **Claude Code example**: ```bash # 1. Register this repository as a marketplace (one-time) /plugin marketplace add bitbankinc/bitbank-lab-mcp # 2. Install plugin /plugin install bitbank-lab-mcp@bitbank-lab ``` # Tool List `/reload-plugins` `bitbank-lab` refers to the marketplace name provided by this repository (the `name` field in `.claude-plugin/marketplace.json`), and `bitbank-lab-mcp` refers to the plugin name. After execution, the input UI for bitbank API key / API secret will be displayed. **If you only use Public tools, you can leave both blank** — Private API tools are automatically enabled only when you enter the API key. > If you want to add or change the API key later, please open the settings of the corresponding plugin from `/plugin`, and update `api_key` / `api_secret`. In Claude Code, it is stored in the OS keychain because of `sensitive: true`. **For Cursor / Codex (via environment variables)**: After running `/plugin install`, please set the environment variables in the shell as follows before starting Cursor / Codex (not required if you only use Public tools): ```bash export BITBANK_API_KEY="your_api_key" export BITBANK_API_SECRET="your_api_secret" ``` On macOS / Linux, you can add it to `~/.zshrc` or `~/.bashrc` for persistence. On Windows, use the environment variable management screen or `setx`. ### 4. Try it out Talk to the AI client directly: ``` Analyze the current market situation of BTC Which is more dominant, buying or selling Bitcoin? Please provide 3 cryptocurrencies that have technically improved in the last week ``` 💡 **If you don't know what to ask**: Please refer to [the prepared prompt collection](docs/prompts-table.md). We have prepared 9 types of analysis prompts for beginners 🔰 to intermediate users. 🌅 **For morning routine**: You can quickly catch up on market fluctuations during sleep with the "Good Morning Report". ## Private API (Trading Function) The server automatically switches the functions it exposes depending on the presence or absence of the API key. | Setting | Number of Tools | Number of Prompts | Available Functions | |------|---------|------------|-----------| | No key set | 32 (only Public) | 8 | Price acquisition, technical analysis, chart generation, backtesting | | Key set | 32 + 16 = **48** | 8 + 1 = **9** | Above + asset confirmation, order, portfolio analysis | When the key is not set, Private tools and prompts are not displayed on the MCP client at all (not an error, but not registered). ### Environment Variable Settings **When starting from the terminal:** ```bash export BITBANK_API_KEY="your_api_key" export BITBANK_API_SECRET="your_api_secret" ``` **When using Plugin install** — Open the settings of the corresponding plugin from `/plugin`, and input `api_key` / `api_secret` to complete (no manual editing required). **When manually setting in Claude Desktop** — Add to `env` in `claude_desktop_config.json` (add to the npx method or absolute path method set in [Section 1](#1-claude-desktop-recommended)): ```json { "mcpServers": { "bitbank-lab": { "command": "npx", "args": ["-y", "bitbank-lab-mcp"], "env": { "BITBANK_API_KEY": "your_api_key", "BITBANK_API_SECRET": "your_api_secret" } } } } ``` Please issue the API key from the [bitbank settings screen](https://app.bitbank.cc/account/api). **It is strongly recommended to grant only the minimum necessary permissions** (principle of least privilege). | What you want to do | Required permissions | |---|---| | Asset confirmation, portfolio analysis (read-only) | **Only "Reference"** ← Safest, if in doubt, choose this | | Above + AI to place and cancel orders | "Reference" + "Transaction" | ⚠️ **Do not activate the "Withdrawal" permission** at all. This MCP server does not implement withdrawal tools, so there is no need to grant this permission. To avoid asset outflow in case of leakage. **IP restrictions**: If you can set IP restrictions for the API key on bitbank, please set them as much as possible. | Category | Tool | Description | Required permissions | |---|---|---|---| | Account information | `get_my_assets` | List of held assets | Reference | | Order inquiry | `get_my_orders`, `get_order`, `get_orders_info` | Order inquiry | Reference | | Trading history | `get_my_trade_history` | Trading history acquisition | Reference | | Portfolio | `analyze_my_portfolio` | Profit and loss analysis, performance | Reference | | Deposit and withdrawal | `get_my_deposit_withdrawal` | Deposit and withdrawal history | Reference | | Margin trading | `get_margin_status`, `get_margin_positions`, `get_margin_trade_history` | Margin, position, trading history | Reference | | Order placement | `preview_order` → `create_order` | 2-step confirmation order placement | Transaction | | Cancellation | `preview_cancel_order` → `cancel_order` | 2-step confirmation cancellation | Transaction | | Batch cancellation | `preview_cancel_orders` → `cancel_orders` | 2-step confirmation batch cancellation | Transaction | Transaction operations (order placement, cancellation) **must be confirmed in 2 steps** . It cannot be executed without the confirmation token (HMAC-SHA256, default 60 seconds valid) issued by the preview tool. Details: [docs/private-api.md](docs/private-api.md) ## Usage Examples (Conversation Types) - "Is BTC buying now?" → `analyze_market_signal`: Overall score + contribution degree, grounds - "Which stocks have crossed MACD recently?" → `detect_macd_cross`: Screening results - "I want to see the volatility transition for the past 30 days" → `get_volatility_metrics` + `render_chart_svg` ## Chart Display (SVG) - In the MCP client (Claude), please request to display `data.svg` as an artifact. - If Claude's LLM cannot output artifacts well, it is recommended to add the following prompt. - "Add identifier and title and display as an artifact" - The default rendering is "candlestick only". Overlay such as Bollinger Bands is added when explicitly specified (BB is added when `--bb-mode=default` is specified). ## Detailed Documents - Prompt collection (for beginners to intermediate users): [docs/prompts-table.md](docs/prompts-table.md) - Tool list and usage: [docs/tools.md](docs/tools.md) - Private API guide: [docs/private-api.md](docs/private-api.md) - Change history: [CHANGELOG.md](CHANGELOG.md) - Developer guide (type generation, CI, etc.): [CLAUDE.md](CLAUDE.md) - Operation and monitoring (log aggregation / Docker startup, etc.): [docs/ops.md](docs/ops.md) ## Frequently Asked Questions (FAQ) **Q. I don't know what to ask** Refer to [prompt collection](docs/prompts-table.md). We have prepared 9 types of analysis prompts for beginners 🔰 to intermediate users. **Q. Is Docker mandatory?** No. You can run it locally with Node 18+ (the shortest is Claude Desktop registration). **Q. Is an API key required?** Not required for public data acquisition and analysis. If you use Private API, refer to [Private API guide](docs/private-api.md). **Q. Which tool should I use?** First, grasp the whole situation with `analyze_market_signal` → move to each specialized tool as needed. **Q. Are the supported stocks fixed?** Not fixed. Automatically follow the stocks returned by the upstream public API (automatically reflected in addition/removal). Reference: [bitbank public API specifications](https://github.com/bitbankinc/bitbank-api-docs/blob/master/public-api.md) **Q. Can I try it with MCP Inspector?** Yes. You can do it next (operation confirmation for npm public version). ```bash npx @modelcontextprotocol/inspector -- npx -y bitbank-lab-mcp ``` If you start from the source code, use `npx @modelcontextprotocol/inspector -- tsx src/server.ts` (refer to [developer](#developer)) **Q. There is little or old data for today's trading (flow)** bitbank's specifications. The date archive of trading history (`/transactions/{YYYYMMDD}`) is **in UTC calendar day units**, and is only released after the UTC day is completed (after Japan time 9:00 am, with further public delay). The trading data for the current UTC day can only be acquired up to about 60 latest (latest), so the coverage in the `get_flow_metrics` etc. is limited (explicitly indicated as a warning). ## Troubleshooting | Symptoms | Cause and countermeasure | |------|-----------| | Tools not displayed on Claude Desktop | `claude_desktop_config.json` JSON syntax is broken / Claude Desktop not restarted with `Cmd+Q` (Windows quits completely) | | "Cannot connect to server" error (npx method) | `npx` not found from Claude Desktop. Switch to [absolute path method](#absolute-path-method-fallback). | | `spawn npx ENOENT` error | `which npx` points to a different path. Rewrite `command` to the correct path. | | MCP stopped working after Node.js update | For nvm/volta, Node.js version changes, absolute path also changes. Reconfirm `which npx` and update `command`, or switch to npx method (`npx` name designation). | | `Cannot find package 'tsx'` error | `bitbank-lab-mcp` old version (v0.1.0) causes this issue. Update to the latest version with `npx -y bitbank-lab-mcp@latest`, or restart settings | | Timeout during tool execution | Check network connection / check [bitbank API status](https://status.bitbank.cc/) | | Private API tools not displayed | Confirm both `BITBANK_API_KEY` and `BITBANK_API_SECRET` are set (→ [docs/private-api.md](docs/private-api.md)) | | Want to check logs | Add `"LOG_LEVEL": "debug"` to `env` and restart | | "Marketplace not found" during Plugin install | Execute `/plugin marketplace add bitbankinc/bitbank-lab-mcp` first, then `/plugin install bitbank-lab-mcp@bitbank-lab` | --- ## For Developers (Starting from Source) This section is for developers who want to customize the MCP server or send PRs. **For normal users, use the `npx -y bitbank-lab-mcp` method in [Section 1](#1-claude-desktop-recommended)** (no cloning required). ### Setup ```bash git clone https://github.com/bitbankinc/bitbank-lab-mcp.git cd bitbank-lab-mcp npm ci ``` Use `npm ci` instead of `npm install` to install dependencies according to `package-lock.json` (CI also uses `npm ci`). No build steps are required (execute TypeScript directly with tsx). ### STDIO Mode (for Claude Desktop / Claude Code) If you want to use the local development version from Claude Desktop, register it with an absolute path in `claude_desktop_config.json`: ```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" } } } } ``` Replace `/ABS/PATH/to/` with the actual clone path (confirmed with `pwd`). For operation confirmation with Inspector: ```bash npx @modelcontextprotocol/inspector -- tsx src/server.ts ``` ### Local Development on Windows In environments where `npx` cannot resolve the path, specify the absolute path of `node` and the CLI of `tsx`: ```json { "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 / Type Generation / Linter Refer to [CLAUDE.md](CLAUDE.md) for development commands ( `npm test` / `npm run lint:fix` / `npm run gen:types`, etc.). ## Feedback and Bug Reports Please report bugs and feature requests from [GitHub Issues](https://github.com/bitbankinc/bitbank-lab-mcp/issues). We have prepared an issue template, so please select the one that suits your needs. ## Disclaimer ### Development Stage This tool is in the development stage (beta version). It may contain bugs, malfunctions, errors, or inaccurate analysis results. ### Processing Results by AI Agents The data provided by this MCP server / CLI tool **does not guarantee the accuracy, completeness, usefulness, or latest information** of the processing results by AI agents. The processing results by AI agents may cause the order type, price, quantity, and other trading conditions to be processed or executed in a form different from the user's intention. ### Position under the Financial Instruments and Exchange Act This MCP server is provided for information provision purposes only and is not intended for investment advice, agency business, investment solicitation, or other acts under the Financial Instruments and Exchange Act. ### Dependence on External Services This MCP server depends on external APIs, LLMs, and third-party services, and if these specifications change, stop, or malfunction, this MCP server may not function normally. ### Supplementary Nature of Safety Measures The final order confirmation function, validation, and other safety measures implemented in this MCP server are auxiliary functions to prevent erroneous operations or erroneous orders, and do not guarantee their complete prevention. ### User Responsibility Users confirm the information and order content provided and generated by this MCP server, and use this MCP server at their own judgment and responsibility, make investment decisions, execute orders, and conduct transactions. ### Limitation of Liability We are not liable for any damages related to the use or inability to use this MCP server, or the information, processing results by AI agents, or transaction operations provided and generated by this MCP server, except in cases of our intentional or gross negligence. ### API Key and Authentication Information Management API keys and passwords required for transactions must be properly managed by the users themselves. Please be aware not to enter or post API keys, transaction passwords, or other authentication information in chat boxes, public repositories, or other publicly accessible environments. We are not responsible for any damages caused by users' inadequate management, incorrect input, leakage, or third-party use of authentication information, except in cases of our intentional or gross negligence.