bybit-official-trading-server 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bybit-exchange
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# @bybit-exchange/mcp-server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes Bybit REST and WebSocket APIs as MCP tools, enabling AI assistants (Claude, Cursor, etc.) to query market data and manage accounts on Bybit.
+
+[中文文档](./README.zh.md)
+
+---
+
+## Features
+
+- **Market Data** — Klines, orderbook, tickers, funding rates, open interest, risk limits, and more (22 tools, no auth required)
+- **Account** — Wallet balance, transaction logs, fee rates, collateral info, MMP state, DCP config, SMP group, and more (11 tools, auth required)
+- **Asset** — Asset overview, portfolio margin, delivery/settlement records, total member assets (5 tools, auth required)
+- **User** — API key info, sub-account listing, member account type, referral queries (7 tools, auth required)
+- **WebSocket** — Subscribe-snapshot pattern for real-time orderbook, tickers, klines, executions, positions, wallet, RFQ, spread trading, and more (26 tools)
+- **HMAC-SHA256 signing** — Automatic request signing for all authenticated endpoints
+- **Rate limiting** — Per-endpoint rate limiting built in
+- **Mainnet / Testnet** — Switch via environment variable
+
+---
+
+## Requirements
+
+- Node.js >= 20.6
+
+---
+
+## Installation
+
+```bash
+npm install -g @bybit-exchange/mcp-server
+```
+
+Or run directly with `npx`:
+
+```bash
+npx @bybit-exchange/mcp-server
+```
+
+---
+
+## Configuration
+
+Set the following environment variables before starting the server:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BYBIT_API_KEY` | For auth endpoints | — | Your Bybit API key |
+| `BYBIT_API_SECRET` | For auth endpoints | — | Your Bybit API secret |
+| `BYBIT_TESTNET` | No | `false` | Set to `true` to use the testnet |
+
+Market data tools work without credentials. Account, asset, user, and WebSocket private channel tools require `BYBIT_API_KEY` and `BYBIT_API_SECRET`.
+
+---
+
+## Usage with Claude Desktop
+
+> **First-time setup:** Claude Desktop will show an authorization prompt the first time each tool is called. Click **"Always allow"** to permanently approve it — you won't be asked again.
+
+Add the following to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "bybit": {
+      "command": "npx",
+      "args": ["-y", "@bybit-exchange/mcp-server"],
+      "env": {
+        "BYBIT_API_KEY": "your_api_key",
+        "BYBIT_API_SECRET": "your_api_secret"
+      }
+    }
+  }
+}
+```
+
+For testnet:
+
+```json
+{
+  "mcpServers": {
+    "bybit": {
+      "command": "npx",
+      "args": ["-y", "@bybit-exchange/mcp-server"],
+      "env": {
+        "BYBIT_API_KEY": "your_testnet_api_key",
+        "BYBIT_API_SECRET": "your_testnet_api_secret",
+        "BYBIT_TESTNET": "true"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Usage with Cursor / VS Code
+
+Add to your MCP settings file:
+
+```json
+{
+  "mcpServers": {
+    "bybit": {
+      "command": "npx",
+      "args": ["-y", "@bybit-exchange/mcp-server"],
+      "env": {
+        "BYBIT_API_KEY": "your_api_key",
+        "BYBIT_API_SECRET": "your_api_secret"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Available Tool Categories
+
+| Category | Auth | Description |
+|----------|------|-------------|
+| `market` | No | Klines, orderbook, tickers, funding rates, open interest, volatility, risk limits, long/short ratio, delivery price, insurance pool, and more (22 tools) |
+| `account` | Yes | Wallet balance, transaction log, fee rates, collateral settings, option Greeks, MMP state, DCP config, SMP group, account instruments, and more (11 tools) |
+| `asset` | Yes | Asset overview, portfolio margin, delivery/settlement records, aggregated parent+sub account assets (5 tools) |
+| `user` | Yes | API key info & permissions, sub-account listing, member account types, referral/invitation queries (7 tools) |
+| `websocket` | Mixed | Real-time snapshots via subscribe-snapshot pattern: orderbook, tickers, klines, trades, liquidations, executions, positions, wallet, option Greeks, RFQ block trades, spread trading (26 tools) |
+
+---
+
+## Example Prompts
+
+Once connected to an AI assistant, you can use natural language:
+
+**Market data:**
+- "What is the current BTC/USDT price?"
+- "Show me the order book for ETHUSDT with depth 50"
+- "Get the last 10 BTC perpetual klines on the 1-hour interval"
+- "What are the current funding rates for the top 5 perpetual contracts?"
+- "What's the open interest for BTCUSDT?"
+
+**Account & Asset:**
+- "What's my wallet balance?"
+- "Show me my recent transaction log"
+- "What are my maker/taker fee rates?"
+- "Show me my total assets across all sub-accounts"
+- "What's my portfolio margin status?"
+
+**User & Sub-accounts:**
+- "List all my sub-accounts"
+- "Show me the permissions and VIP level of my current API key"
+- "What account types do my sub-accounts use?"
+- "Who have I invited through the referral program?"
+
+**WebSocket / Real-time:**
+- "Subscribe to the BTCUSDT orderbook and give me a snapshot"
+- "Get the latest execution records from my account"
+- "What are my current open positions?"
+
+---
+
+## WebSocket Pattern Details
+
+WebSocket tools are compatible with MCP's request/response model:
+
+1. The tool opens a WebSocket connection to Bybit's streaming endpoint
+2. Subscribes to the requested channel (with auth handshake for private channels)
+3. Collects the specified number of messages (default: 1) or waits up to `timeoutMs` (default: 5000 ms)
+4. Returns the collected snapshot and closes the connection
+
+This makes real-time data accessible in a single tool call without managing persistent connections.
+
+---
+
+## Security Notes
+
+- API keys are read from environment variables at call time, never hardcoded
+- All authenticated requests use HMAC-SHA256 signing per Bybit's V5 API specification
+- Never share your API secret or commit it to source control
+- Use API keys with minimal required permissions (read-only where possible)
+
+---
+
+## Local Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start the server in development mode
+npm run dev
+
+# Type check
+npm run typecheck
+
+# Build for production
+npm run build
+```
+
+---
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,203 @@
+# @bybit-exchange/mcp-server
+
+将 Bybit REST 和 WebSocket API 封装为 [MCP（模型上下文协议）](https://modelcontextprotocol.io) 工具的服务器，让 AI 助手（Claude、Cursor 等）可以直接用自然语言查询行情数据、管理 Bybit 账户。
+
+[English Documentation](./README.md)
+
+---
+
+## 功能特性
+
+- **行情数据** — K 线、订单薄、Ticker、资金费率、持仓量、风险限额等（22 个工具，无需鉴权）
+- **账户管理** — 钱包余额、交易日志、手续费率、抵押品信息、MMP 状态、DCP 配置、SMP 分组等（11 个工具，需要鉴权）
+- **资产管理** — 资产总览、组合保证金、交割/结算记录、全账户聚合资产（5 个工具，需要鉴权）
+- **用户管理** — API Key 信息、子账户列表、账户类型查询、邀请返佣查询（7 个工具，需要鉴权）
+- **WebSocket** — 快照模式实时订阅订单薄、Ticker、K 线、成交、仓位、钱包、RFQ、价差合约等（26 个工具）
+- **HMAC-SHA256 签名** — 鉴权请求自动签名，无需手动处理
+- **频率限制** — 内置按接口的频率控制
+- **主网 / 测试网** — 通过环境变量切换
+
+---
+
+## 环境要求
+
+- Node.js >= 20.6
+
+---
+
+## 安装
+
+```bash
+npm install -g @bybit-exchange/mcp-server
+```
+
+或直接通过 `npx` 运行（无需全局安装）：
+
+```bash
+npx @bybit-exchange/mcp-server
+```
+
+---
+
+## 配置
+
+启动前设置以下环境变量：
+
+| 变量名 | 是否必填 | 默认值 | 说明 |
+|--------|----------|--------|------|
+| `BYBIT_API_KEY` | 鉴权接口必填 | — | Bybit API Key |
+| `BYBIT_API_SECRET` | 鉴权接口必填 | — | Bybit API Secret |
+| `BYBIT_TESTNET` | 否 | `false` | 设为 `true` 使用测试网 |
+
+行情类工具无需填写 API 凭证。账户、资产、用户类工具以及 WebSocket 私有频道需要同时设置 `BYBIT_API_KEY` 和 `BYBIT_API_SECRET`。
+
+---
+
+## 在 Claude Desktop 中使用
+
+> **首次使用提示：** Claude Desktop 会在每个工具第一次调用时弹出授权确认框。点击 **"Always allow"** 即可永久免授权，后续调用不再弹出。
+
+在 `claude_desktop_config.json` 中添加以下配置：
+
+```json
+{
+  "mcpServers": {
+    "bybit": {
+      "command": "npx",
+      "args": ["-y", "@bybit-exchange/mcp-server"],
+      "env": {
+        "BYBIT_API_KEY": "你的 API Key",
+        "BYBIT_API_SECRET": "你的 API Secret"
+      }
+    }
+  }
+}
+```
+
+使用测试网：
+
+```json
+{
+  "mcpServers": {
+    "bybit": {
+      "command": "npx",
+      "args": ["-y", "@bybit-exchange/mcp-server"],
+      "env": {
+        "BYBIT_API_KEY": "你的测试网 API Key",
+        "BYBIT_API_SECRET": "你的测试网 API Secret",
+        "BYBIT_TESTNET": "true"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 在 Cursor / VS Code 中使用
+
+在 MCP 配置文件中添加：
+
+```json
+{
+  "mcpServers": {
+    "bybit": {
+      "command": "npx",
+      "args": ["-y", "@bybit-exchange/mcp-server"],
+      "env": {
+        "BYBIT_API_KEY": "你的 API Key",
+        "BYBIT_API_SECRET": "你的 API Secret"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 工具分类
+
+| 分类 | 是否需要鉴权 | 说明 |
+|------|------------|------|
+| `market` | 否 | K 线、订单薄、Ticker、资金费率、持仓量、历史波动率、风险限额、多空比、交割价格、保险基金等（22 个工具） |
+| `account` | 是 | 钱包余额、交易日志、手续费率、抵押品设置、期权希腊值、MMP 状态、断线保护、防自成交分组、可划转金额等（11 个工具） |
+| `asset` | 是 | 资产总览、组合保证金、交割/结算记录、母子账户聚合资产（5 个工具） |
+| `user` | 是 | API Key 信息与权限、子账户列表、成员账户类型、邀请返佣查询（7 个工具） |
+| `websocket` | 混合 | 订阅-快照模式实时数据：订单薄、Ticker、K 线、成交、强平、仓位、钱包、期权希腊值、RFQ 大宗交易、价差合约等（26 个工具） |
+
+---
+
+## 使用示例
+
+接入 AI 助手后，可以用自然语言提问：
+
+**行情数据：**
+- "BTC/USDT 现在多少钱？"
+- "给我看一下 ETHUSDT 深度为 50 的订单薄"
+- "查一下 BTC 永续合约最近 10 根小时 K 线"
+- "前 5 大永续合约当前资金费率分别是多少？"
+- "BTCUSDT 当前的未平仓量是多少？"
+
+**账户与资产：**
+- "我的钱包余额是多少？"
+- "查一下我最近的交易日志"
+- "我的 Maker/Taker 费率是多少？"
+- "列出我所有账户的聚合资产"
+- "查看我的组合保证金状态"
+
+**用户与子账户：**
+- "列出我所有的子账户"
+- "查看当前 API Key 的权限和 VIP 等级"
+- "我的子账户分别是什么账户类型？"
+- "查看我通过邀请码邀请的用户"
+
+**WebSocket 实时数据：**
+- "订阅 BTCUSDT 订单薄，给我一个快照"
+- "获取我账户最新的成交记录"
+- "查看我当前的仓位状态"
+
+---
+
+## WebSocket 工具说明
+
+WebSocket 工具与 MCP 的请求/响应模型兼容：
+
+1. 工具建立 WebSocket 连接到 Bybit 行情推送地址
+2. 订阅指定频道（私有频道会先完成鉴权握手）
+3. 收集指定数量的消息（默认 1 条），或等待 `timeoutMs`（默认 5000 ms）后超时返回
+4. 返回快照数据并关闭连接
+
+这样一来，实时数据可在单次工具调用中完整返回，无需维护长连接。
+
+---
+
+## 安全注意事项
+
+- API Key 从环境变量读取，不会硬编码在任何地方
+- 所有鉴权请求遵循 Bybit V5 API 规范，使用 HMAC-SHA256 签名
+- 请勿泄露 API Secret，也不要将其提交到代码仓库
+- 建议为 API Key 设置最小权限（只读权限优先）
+
+---
+
+## 本地开发
+
+```bash
+# 安装依赖
+npm install
+
+# 开发模式启动
+npm run dev
+
+# 类型检查
+npm run typecheck
+
+# 生产构建
+npm run build
+```
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "bybit-official-trading-server",
+  "version": "2.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Bybit trading MCP server — exposes Bybit REST and WebSocket APIs as MCP tools",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "trading-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "node --env-file=.env --import tsx/esm src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "bump": "bash scripts/bump-version.sh",
+    "gen-manifest": "bash scripts/gen-manifest.sh"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.2",
+    "ws": "^8.18.0",
+    "zod": "^3.24.2",
+    "zod-to-json-schema": "^3.24.5"
+  },
+  "devDependencies": {
+    "js-yaml": "^4.1.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.13",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=20.6"
+  }
+}