MCP Bybit API Interface

Bybit MCP (Model Context Protocol) Server. Provides a convenient interface to interact with the Bybit V5 API using MCP tools. Allows fetching market data, managing account information, and placing/canceling orders via API calls wrapped as tools.

⚠️ Security & Safety

This server can place real trades with real money. Read this before configuring it:

• Trading is disabled by default. Mutating tools (place_order, cancel_order, amend_order, cancel_all_orders, set_trading_stop, set_margin_mode, set_leverage) return an error unless you explicitly set TRADING_ENABLED=true.
• Use the testnet first. Set TESTNET=true while you experiment. Combine with TRADING_ENABLED=false for a fully read-only setup, or set READONLY_MODE=true to hard-block every mutating tool regardless of other settings.
• Order size is capped. MAX_ORDER_SIZE_USDT (default 100) limits the estimated notional value of an order to guard against accidental large trades.
• API keys are never logged or exposed. No tool returns your keys; logs only report whether a key is present.
• Never commit your API keys. Provide them through environment variables only.

Environment Variables

Tools 🛠️

Market data

• get_orderbook — order book (category, symbol, limit?).
• get_kline — candlesticks (category, symbol, interval, start?, end?, limit?).
• get_tickers — ticker info (category, symbol).
• get_public_trade_history — recent public trades (category, symbol, limit?).
• get_instruments_info — instrument metadata / limits (category, symbol, status?, baseCoin?).
• get_funding_rate_history — funding rate history for perps (category, symbol, startTime?, endTime?, limit?).
• get_open_interest — open interest over time (category, symbol, intervalTime?, ...).
• get_fee_rate — maker/taker fee rates (category, symbol?, baseCoin?).
• get_server_time — Bybit server time.
• market_snapshot — composite market view (orderbook + ticker + kline + instrument + recent trades, plus funding rate & open interest for futures) in a single call.

Account

• get_wallet_balance — balances (accountType, coin?).
• get_positions — open positions (category, symbol?).
• get_order_history — historical orders.
• get_open_orders — current open orders.
• get_api_key_information — API key details.

Trading (mutating — requires TRADING_ENABLED=true)

• validate_order — pre-flight validation; never places an order. Not blocked by trading flags.
• place_order — place an order; supports dry_run=true to validate without placing.
• amend_order — modify an existing order in place.
• cancel_order — cancel a single order.
• cancel_all_orders — cancel all open orders (optionally scoped).
• set_trading_stop — set take profit / stop loss / trailing stop.
• set_margin_mode — set isolated/cross margin.
• set_leverage — set leverage for a futures symbol.

(Refer to the function docstrings in the code for detailed parameter descriptions and examples.)

Development

uv sync --group dev   # install dev dependencies (pytest, ruff)
uv run ruff check .   # lint
uv run pytest -q      # run the unit test suite (no live API calls)

CI (GitHub Actions) runs lint + tests on every push/PR; Docker images are built and published automatically on pushes to main.

Contact & Support

For additional inquiries or support, please contact:

• Email: dlwjdtn5624@naver.com

We welcome your questions and feedback!

Installation

Requires Python 3.12+. This project uses uv.

git clone https://github.com/dlwjdtn535/mcp-bybit-server.git
cd mcp-bybit-server
uv sync
uv run mcp-bybit-server   # runs the MCP server over stdio

After install, the mcp-bybit-server command is the entry point used by the MCP client configs below.

Installing via Smithery

To install this Bybit API Interface server for Claude Desktop automatically via Smithery:

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

Configuration (Claude Desktop, Cline, Roo Code, etc.)

Add one of the following to your MCP settings file (e.g. claude_desktop_config.json / mcp_settings.json).

Using uv (run from a cloned repo):

{
  "mcpServers": {
    "bybit": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp-bybit-server",
        "mcp-bybit-server"
      ],
      "env": {
        "ACCESS_KEY": "YOUR_BYBIT_API_KEY",
        "SECRET_KEY": "YOUR_BYBIT_SECRET_KEY",
        "TESTNET": "true",
        "TRADING_ENABLED": "false"
      }
    }
  }
}

On Windows, use an absolute path with double backslashes (e.g. C:\\Users\\YOUR_USERNAME\\mcp-bybit-server).

Using Docker:

First pull the image: docker pull dlwjdtn535/mcp-bybit-server:latest

{
  "mcpServers": {
    "bybit-server-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "ACCESS_KEY=YOUR_BYBIT_API_KEY",
        "-e", "SECRET_KEY=YOUR_BYBIT_SECRET_KEY",
        "-e", "TESTNET=true",
        "-e", "TRADING_ENABLED=false",
        "-e", "MAX_ORDER_SIZE_USDT=100",
        "dlwjdtn535/mcp-bybit-server:latest"
      ]
    }
  }
}

Note: Always use @latest or a specific version tag for both NPX and Docker to ensure you are using the intended version.

API Key Setup

To use this Bybit API interface, create an API key from Bybit:

1. Log into your Bybit account.
2. Navigate to API Management.
3. Create a new API key.
4. Important security settings:
   • Enable IP restriction if possible, and add ONLY the IP address(es) the server runs from.
   • Never share your API keys or expose them in public repositories.
   • Recommended permissions:
     • Read (required)
     • Trade (required only if you enable order execution)
     • Wallet (required for balance checking)

License

MIT License