Registry / devops / bybit-official-trading-server

bybit-official-trading-server

library2.1.7jsnpmunverified

Production-ready MCP server (v2.1.7) exposing 190+ Bybit V5 API tools — market data, trading, account management, WebSocket streams — to AI assistants like Claude, Cursor, VS Code via the Model Context Protocol. Built by Bybit, actively maintained with weekly releases. No API key needed for 22 market-data tools, supports both HMAC and RSA authentication, and instant npx startup. Distinguishes itself by being the official first-party MCP server (vs community wrappers) with comprehensive coverage including options, USDC contracts, and sub-account management.

devops

npm install bybit-official-trading-server

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BYBIT-OFFICIAL-TRA

bybit-official-trading-server

devopsjavascriptv2.1.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ npx bybit-official-trading-server@latest

✗ npm install -g bybit-official-trading-server && bybit-official-trading-server

This is a CLI server, not a library. Always use npx to get the latest version. Global install is not recommended.

mcp.json config for Cursor

✓ {"mcpServers":{"bybit":{"command":"npx","args":["-y","bybit-official-trading-server@latest"],"env":{"BYBIT_API_KEY":"...","BYBIT_API_SECRET":"..."}}}}

✗ {"command":"node","args":["path/to/server.js"]}

Must use npx in command field. For Cursor >0.45, use mcp.json; for older versions use .cursor/mcp.json.

claude_desktop_config.json

✓ {"mcpServers":{"bybit":{"command":"npx","args":["-y","bybit-official-trading-server@latest"],"env":{"BYBIT_API_KEY":"...","BYBIT_API_SECRET":"..."}}}}

✗ {"command":"bybit-official-trading-server"}

Claude Desktop requires full npx command with -y flag for auto-confirmation. Testnet can be enabled by adding BYBIT_TESTNET=true.

CommonJS require (NOT SUPPORTED)

✓ npx bybit-official-trading-server@latest

✗ const server = require('bybit-official-trading-server')

This is not a library. You cannot import/require it in code. It is exclusively a CLI tool launched via npx or configured in MCP client settings.

Minimal configuration to connect Claude Desktop, Cursor, or VS Code to Bybit MCP server. Add your API key and secret, then test with a price query.

// file: .cursor/mcp.json (Cursor) or claude_desktop_config.json (Claude Desktop) { "mcpServers": { "bybit": { "command": "npx", "args": ["-y", "bybit-official-trading-server@latest"], "env": { "BYBIT_API_KEY": process.env.BYBIT_API_KEY ?? '', "BYBIT_API_SECRET": process.env.BYBIT_API_SECRET ?? '', // Optional: "BYBIT_TESTNET": "true" } } } } // Restart your AI assistant and ask: // "What is the current price of BTCUSDT?"

Debug

Known issues

breakingRSA authentication requires both BYBIT_API_KEY and BYBIT_API_PRIVATE_KEY_PATH. If BYBIT_API_SECRET is also set, RSA takes priority (no error, but warning logged).

fix

Remove BYBIT_API_SECRET when using RSA mode to avoid confusion. Set BYBIT_API_PRIVATE_KEY_PATH to absolute path of private key PEM file.

affects: =2.1.7

gotchaBeware of rate limits: Bybit API has per-endpoint rate limits. The MCP server does not throttle requests automatically.

fix

Implement client-side throttling or monitor 429 responses. Refer to Bybit API docs for rate limit tables.

affects: *

gotchaWebSocket tools require active connection; stale connections may drop without warning. The server auto-reconnects but there is a brief gap.

fix

Design your AI prompts to tolerate transient failures. Re-query if no data received within 10 seconds.

affects: *

deprecatedNode.js <20.6 is not supported. Engine requirement is >=20.6.

fix

Upgrade Node.js to v20.6 or later. Check with `node --version`.

affects: >=2.1.0

breakingV5 API migration: The MCP server exclusively uses Bybit V5 REST and WebSocket APIs. V3 API endpoints are not available.

fix

Use V5 endpoints only. If you have legacy V3 integrations, do not migrate to this MCP server expecting V3 compatibility.

affects: >=1.0.0

Errors

Common errors & fixes

Connection refused: npx bybit-official-trading-server@latest fails with EACCES or ENOENT

npx not installed or permission issue on macOS/Linux.

fix

Ensure Node.js >=20.6 is installed. Run `node --version` and `npx --version`. If missing, install via `npm install -g npx`.

Error: Missing required environment variable: BYBIT_API_KEY

Attempted to use authenticated API tools without setting BYBIT_API_KEY.

fix

Add BYBIT_API_KEY to your MCP client config env or use BYBIT_API_KEY=your_key npx ...` if running directly. Market-data tools do not need this.

X-BAPI-SIGN-TYPE: 2 header missing leads to auth error

RSA mode requires X-BAPI-SIGN-TYPE header set to 2; the server does this automatically if BYBIT_API_PRIVATE_KEY_PATH is set.

fix

If using RSA, ensure BYBIT_API_PRIVATE_KEY_PATH is set correctly. If using HMAC, set BYBIT_API_SECRET. Do not set both.

Cannot read properties of undefined (reading 'env') in Cursor

Cursor's MCP config JSON is invalid (missing opening brace or typo).

fix

Validate JSON at jsonlint.com. Ensure structure: { "mcpServers": { "bybit": { ... } } }.

Upgrade

Version history

2.1.7latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredMCP SDK for server implementation

Agent activity

11 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/bybit-exchange/trading-mcp ↗

packagebybit-official-trading-server ↗

homepagehttps://github.com/bybit-exchange/trading-mcp#readme ↗