Bybit API Connector for Model Context Protocol (MCP)

This server acts as an MCP gateway for the Bybit trading platform, abstracting REST API complexities into structured tool calls. It supports querying market depth, historical price bars (K-lines), account metrics, and trade lifecycle management.

Deployment Instructions

Automated Installation via Smithery CLI

To integrate this exchange adapter swiftly into your Claude Desktop environment via Smithery:

bash npx -y @smithery/cli install @dlwjdtn535/mcp-bybit-server --client claude

Manual Configuration for Local Execution (uv/Python)

Configure your central MCP settings file (e.g., mcp_settings.json) to point to your running server instance. Below are platform-specific examples assuming execution via the uv ASGI server.

Windows Setup (Note double backslashes for path escaping):

{ "mcpServers": { "bybit-connector-win": { "command": "uv", "args": [ "run", "--directory", "C:\Users\YOUR_USERNAME\AppData\Local\Programs\bybit-adapter\src", "main_service.py" ], "env": { "ACCESS_KEY": "{ACCESS_KEY}", "SECRET_KEY": "{ACCESS_KEY}" } } } }

macOS Setup:

{ "mcpServers": { "bybit-connector-mac": { "command": "uv", "args": [ "run", "--directory", "/usr/local/bin/bybit-adapter/src", "main_service.py" ], "env": { "ACCESS_KEY": "{ACCESS_KEY}", "SECRET_KEY": "{ACCESS_KEY}" } } } }

Linux Setup:

{ "mcpServers": { "bybit-connector-lin": { "command": "uv", "args": [ "run", "--directory", "/home/YOUR_USERNAME/bin/bybit-adapter/src", "main_service.py" ], "env": { "ACCESS_KEY": "{ACCESS_KEY}", "SECRET_KEY": "{ACCESS_KEY}" } } } }

Docker Container Deployment

Prerequisite: Pull the designated Docker image: docker pull dlwjdtn535/mcp-bybit-server:latest

{ "mcpServers": { "bybit-server-docker": { "command": "docker", "args": [ "run", "-i", "--rm", "--init", "-e", "ACCESS_KEY={ACCESS_KEY}", "-e", "SECRET_KEY={SECRET_KEY}", "dlwjdtn535/mcp-bybit-server:latest" ] } } }

Crucial Note: When installing via NPX or deploying via Docker, always specify the @latest tag or a concrete version identifier to guarantee functional compatibility.

Available Exchange Interaction Tools 🛠️

This adapter exposes the following callable functions for Bybit API interaction:

1. query_market_depth: Retrieves the current state of the order book.
   • Parameters: category (e.g., linear, inverse), symbol (e.g., BTCUSDT), limit (optional).
   • Output: Detailed order book structure.
2. fetch_candlestick_data: Obtains historical time-series bar data.
   • Parameters: category, symbol, interval (e.g., 1m, 4h), optional start/end timestamps, optional limit.
   • Output: Array of candlestick records.
3. get_current_tickers: Fetches aggregated ticker statistics.
   • Parameters: category, symbol.
   • Output: Real-time ticker summary.
4. retrieve_account_capital: Checks the current balance across specified assets/account types.
   • Parameters: accountType, optional coin.
   • Output: Account asset summary.
5. examine_positions: Retrieves open position details.
   • Parameters: category, optional symbol.
   • Output: Current exposure information.
6. execute_trade_order: Submits a new trading instruction (e.g., Limit, Market).
   • Parameters: category, symbol, side (Buy/Sell), orderType, qty, conditional parameters like price (for limit orders), positionIdx, timeInForce, risk parameters (takeProfit, stopLoss).
   • Output: Order placement confirmation receipt.
7. invalidate_active_order: Sends a request to cancel an existing order.
   • Parameters: category, symbol, requires either orderId or orderLinkId.
   • Output: Order cancellation status.
8. fetch_transaction_log: Retrieves records of previously settled orders.
   • Parameters: category, optional symbol, orderId, limit, etc.
   • Output: Historical order data.
9. fetch_pending_instructions: Lists orders that have been accepted but not yet filled.
   • Parameters: category, optional symbol, limit, etc.
   • Output: Active, unfilled order details.
10. configure_risk_stops: Manages protective/profit-taking exit levels for a position.
    • Parameters: category, symbol, optional takeProfit, stopLoss, trailingStop, positionIdx.
    • Output: Configuration success status.
11. adjust_leverage_and_mode: Sets the collateral structure (e.g., Isolated vs. Cross Margin) and leverage levels.
    • Parameters: category, symbol, tradeMode, buyLeverage, sellLeverage.
    • Output: Mode adjustment confirmation.
12. get_api_credentials_status: Verifies the permissions and status associated with the active API credentials.
    • Parameters: None.
    • Output: Key metadata.
13. retrieve_instrument_specs: Gets contractual specifications and trading parameters for listed assets.
    • Parameters: category, optional symbol, status, optional baseCoin.
    • Output: Contract specification data.

(Consult the associated Python source code docstrings for exhaustive parameter definitions and usage examples.)

Prerequisite Environment Variables

Before initiating the service, these secrets must be supplied in the execution environment:

bash export ACCESS_KEY="YOUR_BYBIT_API_KEY" export SECRET_KEY="YOUR_BYBIT_SECRET_KEY" export TESTNET=true # Set to "true" for connecting to the simulation environment; default is live trading.

Securing API Credentials (Bybit Setup)

To establish a functional connection, API credentials must be generated on the Bybit platform:

1. Log into your Bybit account portal.
2. Navigate to the API Management section.
3. Generate a new key pair.
4. Mandatory Security Configuration:
   • Activate IP Address Whitelisting. Restrict access only to the static IPs from which this MCP server instance will be launched (your local machine or cloud server).
   • Never publicly expose these secret keys.
   • Required Permissions: Read (Mandatory), Trade (Mandatory for order actions), Wallet (Mandatory for balance checks).

Project Sustenance and Acknowledgment

Should this integration prove valuable to your operations, consider offering support for ongoing development:

Direct Contribution

Via Bybit Sign-Up

Supporting the project by using our referral link when creating a new Bybit account: - Partner Sign-Up Portal - Referral Code: J1O4JK

Support Channels

For technical issues, feature requests, or general inquiries, connect via: - Email: dlwjdtn5624@naver.com

Feedback and questions are highly appreciated.

Licensing

Distributed under the MIT License terms.