🟡 Bybit MCP Server

The most comprehensive MCP server for Bybit — 247 tools covering the entire Bybit V5 API

Quick Start • Features • Configuration • Tools Reference • Troubleshooting • Contributing

🎯 Overview

Bybit MCP Server enables AI assistants like Claude, Cursor, ChatGPT, and other MCP-compatible clients to interact directly with the Bybit cryptocurrency exchange. Execute trades, manage portfolios, analyze markets, and automate strategies — all through natural language.

Why Bybit MCP?

• 🔥 Complete Coverage — 247 tools spanning every Bybit V5 API endpoint

• 🔐 Secure by Design — API credentials never leave your machine

• 👁️ Read-Only Mode — Use all market tools without any API key

• 📡 Triple Transport — STDIO, SSE, and Streamable HTTP

• 🔌 Universal Compatibility — Works with Claude Desktop, Cursor, ChatGPT, and any MCP client

• ⚡ Zero Config Start — Just uv run bybit.py and go

✨ Features

📈 Trading & Markets

• Spot Trading — Market & limit orders, batch operations

• Derivatives — Linear & inverse perpetuals

• Order Management — Amend, cancel, batch, DCP

• Market Data — Klines, orderbook, tickers, funding rates

• Open Interest — Long/short ratio, ADL alerts

💰 Earn & Lending

• Simple Earn — Stake, redeem, yield tracking

• Crypto Loans — Old & new (fixed + flexible)

• Leveraged Tokens — Subscribe & redeem

• Spot Margin — Cross-margin trading

• OTC Lending — Institutional loan management

🏦 Account & Assets

• Wallet — Deposits, withdrawals, transfers

• Multi-Account — Sub-accounts, universal transfers

• Asset Convert — Crypto-to-crypto, small balance, fiat

• Margin Modes — Cross, isolated, portfolio margin

• Risk Management — MMP, leverage, TP/SL

🛠️ Advanced

• Spread Trading — Spread instruments & orders

• Block Trading (RFQ) — Request for quote workflow

• Broker — Earnings, rate limits, vouchers

• Strategy — Built-in arbitrage detection

• Announcements — Exchange news & system status

🚀 Quick Start

Method 1: Ask AI to Install (Recommended)

Simply tell your AI assistant:

"Help me install the Bybit MCP server from https://github.com/JohnnyWic/bybit-mcp"

Your AI will clone the repo, install dependencies, and configure everything automatically. Works with Claude Code, Cursor, and other MCP-compatible clients.

Method 2: Manual Setup

1. Install

git clone https://github.com/JohnnyWic/bybit-mcp.git
cd bybit-mcp
uv sync

Requires Python ≥ 3.13 and uv.

2. Add to Your MCP Client

Add the following to your MCP config file:

JSON config (Claude Desktop / Cursor):

{
  "mcpServers": {
    "bybit-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/bybit-mcp", "run", "bybit.py"]
    }
  }
}

Claude Code CLI:

claude mcp add bybit-mcp -- uv --directory /path/to/bybit-mcp run bybit.py

3. Configure API Key (Optional)

Create a .env file in the project root:

cp .env.example .env

BYBIT_API_KEY=your_api_key_here
BYBIT_SECRET_KEY=your_secret_key_here
BYBIT_TESTNET=false

Or pass credentials inline in the MCP config:

{
  "mcpServers": {
    "bybit-mcp": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/bybit-mcp", "run", "bybit.py",
        "--bybit-api-key", "YOUR_API_KEY",
        "--bybit-secret-key", "YOUR_SECRET_KEY"
      ]
    }
  }
}

💡 No API key? No problem! All 23 market data tools work without authentication.

🔒 Security Note: Never commit your .env file. It's already in .gitignore.

Transport Modes

uv run bybit.py                                        # STDIO (default)
uv run bybit.py --transport sse --port 8000             # SSE
uv run bybit.py --transport streamable-http --port 8000 # Streamable HTTP

💬 Usage Examples

Check Market Price

"What's the current price of BTC?"

Place a Trade

"Buy 0.01 BTC at market price on spot"

Analyze Funding Rates

"Show me the funding rate history for ETHUSDT over the last 24 hours"

Manage Positions

"What are my open positions? Set a stop loss at 95000 for my BTCUSDT long"

Portfolio Overview

"Show my unified account balance and all open orders"

📊 Available Tools (246)

Total: 246 tools

uv run python -c "
import src.tools
from src import mcp
for name in sorted(mcp._tool_manager._tools):
    print(name)
"

🏗️ Project Structure

bybit-mcp/
├── bybit.py                    # Entry point (backward compatible)
├── src/
│   ├── __init__.py             # Shared FastMCP instance
│   ├── main.py                 # CLI: dotenv + argparse + logging + mcp.run()
│   ├── client.py               # Config singleton + HMAC signing + HTTP methods
│   └── tools/
│       ├── __init__.py         # Auto-imports all tool modules
│       ├── market.py           # 23 tools — public market data
│       ├── trade.py            # 15 tools — order management
│       ├── account.py          # 25 tools — account operations
│       ├── position.py         # 11 tools — position management
│       ├── asset.py            # 41 tools — wallet & transfers
│       ├── lending.py          # 39 tools — crypto loans
│       ├── earn.py             #  6 tools — staking & yield
│       ├── leveraged_token.py  #  5 tools — leveraged tokens
│       ├── spot_margin.py      # 12 tools — spot margin
│       ├── user.py             # 15 tools — sub-accounts & API keys
│       ├── broker.py           # 10 tools — broker services
│       ├── otc.py              #  7 tools — OTC lending
│       ├── spread.py           # 11 tools — spread trading
│       ├── rfq.py              # 15 tools — block trading RFQ
│       ├── pre_upgrade.py      #  6 tools — pre-upgrade data
│       ├── announcement.py     #  2 tools — announcements
│       └── strategy.py         #  2 tools — arbitrage strategies
├── .env.example                # Environment variable template
├── pyproject.toml              # Project config & dependencies
└── LICENSE                     # MIT License

🔧 Troubleshooting

MCP Server Not Loading / "No MCP servers configured"

If you've configured the server but /mcp shows no tools or "No MCP servers configured":

1. Check the correct configuration file

Claude Code reads MCP server config from ~/.claude.json (per-project), not from ~/.claude/settings.json. The recommended way to add the server is via CLI:

claude mcp add bybit-mcp -- uv --directory /path/to/bybit-mcp run bybit.py

This writes the config to the correct location. If you manually edited ~/.claude/settings.json, the server won't be found.

2. Use the full path to uv

Claude Code spawns MCP server subprocesses without loading your shell profile (.zshrc / .zprofile), so PATH may not include ~/.local/bin. Use the absolute path:

# Find your uv path
which uv
# Example output: /Users/yourname/.local/bin/uv

# Add with full path
claude mcp add bybit-mcp -- /Users/yourname/.local/bin/uv --directory /path/to/bybit-mcp run bybit.py

3. Restart Claude Code after configuration changes

MCP servers connect at session startup. After adding or changing config, you must exit and restart Claude Code for changes to take effect.

4. Verify the server starts correctly

Test that the server can start and respond to MCP protocol:

# Test import
uv run python -c "from src.main import main; print('Import OK')"

# Test MCP initialize handshake
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' | uv run bybit.py

If the import fails, run uv sync to install dependencies.

5. Don't run the server manually

Claude Code manages the MCP server process itself via stdio. A manually started server instance is completely separate — Claude Code won't connect to it. Let Claude Code handle the lifecycle automatically.

Quick Diagnosis Checklist

⚠️ Disclaimer

This software is provided for educational and informational purposes only.

• Not Financial Advice — This tool does not provide financial, investment, or trading advice

• Use at Your Own Risk — Cryptocurrency trading involves substantial risk of loss

• API Security — Protect your API credentials; use IP restrictions and disable withdrawal permissions

• Test First — Always test on Bybit Testnet before using real funds (--testnet flag)

• No Warranty — The software is provided "as is" without warranty of any kind

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Adding New Tools

1. Add your tool function in the appropriate src/tools/*.py module

2. Decorate with @mcp.tool()

3. Use _public_get for unauthenticated or _signed_get/_signed_post for authenticated endpoints

4. That's it — tools are auto-registered on import

📚 Resources

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

Built with ❤️ for the Bybit trading community