Labsco
BCusack logo

Bybit MCP Server

★ 5

from BCusack

Access Bybit's v5 API for real-time market data, trading operations, and account information.

🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#automation#devops#git#maps#finance#security#project-mgmt

Bybit MCP Server

⚠️ TRADING WARNING ⚠️
This MCP server can execute REAL TRADING OPERATIONS on Bybit when BYBIT_TRADING_ENABLED=true.
Trading operations use REAL MONEY and can result in FINANCIAL LOSSES.
Always test on testnet first (BYBIT_TESTNET=true) and understand the risks before enabling trading.
Trading is DISABLED by default for safety.

A comprehensive Model Context Protocol (MCP) server that provides full access to Bybit's v5 API. This server enables AI assistants to fetch real-time market data, execute trading operations, manage positions, and access account information from the Bybit cryptocurrency exchange.

🚀 Production Ready

✅ Fully Tested - All endpoints tested and working
✅ Docker Support - Published image available at falconiun/bybit-mcp
✅ VS Code Integration - Ready-to-use configurations provided
✅ Comprehensive API Coverage - Market data, trading, positions, and account management

Features

Core Market Data

  • Server Time: Get current Bybit server time
  • Tickers: Retrieve ticker information for trading symbols
  • Order Book: Get order book depth for any symbol
  • Recent Trades: Access recent trade history

Kline/Candlestick Data

  • Standard Klines: Get OHLCV candlestick data
  • Mark Price Klines: Get mark price historical data
  • Index Price Klines: Get index price historical data
  • Premium Index Klines: Get premium index price data

Trading Information

  • Instruments Info: Get detailed trading instrument information
  • Funding Rate History: Access historical funding rates
  • Open Interest: Get open interest statistics
  • Risk Limits: Retrieve risk limit information

Market Statistics

  • Insurance Fund: Get insurance fund data
  • Long/Short Ratio: Access long/short ratio statistics

Trading Operations (Requires BYBIT_TRADING_ENABLED=true)

  • Order Management: Place, amend, and cancel orders with full control
  • Advanced Order Types: Support for Market, Limit, and conditional/trigger orders
  • Batch Operations: Execute multiple orders in a single request for efficiency
  • Order History: View comprehensive open/closed orders and trade history
  • Real-time Execution: Get immediate feedback on order status and fills
  • Trigger Orders: Conditional orders with price triggers and advanced stop/take profit logic

Position Management (Requires BYBIT_TRADING_ENABLED=true)

  • Position Info: Query real-time position data with detailed metrics
  • Leverage Control: Set and modify position leverage dynamically
  • Margin Management: Switch between cross/isolated margin modes
  • Trading Stops: Set take profit, stop loss, and trailing stops
  • Auto Add Margin: Configure automatic margin addition
  • Position Modes: Switch between one-way and hedge position modes
  • P&L Tracking: Access closed profit and loss records

Account & Wallet Management

  • Wallet Balance: Get comprehensive wallet balance information
  • Single Coin Balance: Query specific coin balances
  • Account Information: Access detailed account information and settings
  • Multiple Account Types: Support for UNIFIED, CONTRACT, SPOT, INVESTMENT accounts

🎯 Key Capabilities

✅ Complete API Coverage

  • Market Data: All Bybit v5 market endpoints (tickers, order book, klines, funding rates, etc.)
  • Trading: Full order lifecycle management (place, amend, cancel, batch operations)
  • Advanced Orders: Conditional/trigger orders with sophisticated entry and exit strategies
  • Positions: Complete position management (leverage, margin, stops, P&L tracking)
  • Account: Wallet balances, account info, and multi-account support

✅ Agent-Optimized Design

  • Clear Tool Descriptions: Each tool has detailed, agent-friendly descriptions explaining purpose and usage
  • Rich Parameter Schemas: Comprehensive JSON schemas with examples, enums, and validation constraints
  • Safety Warnings: Important trading tools include prominent safety warnings and risk notices
  • Usage Guidance: Tools include context about when and how to use them effectively
  • Error Prevention: Schema validation prevents common parameter mistakes before API calls

✅ Production Features

  • Safety First: Trading disabled by default with explicit enablement required
  • Testnet Support: Full testnet integration for safe development and testing
  • Error Handling: Comprehensive error handling with detailed error messages
  • Data Validation: Pydantic models ensure data integrity and type safety
  • Docker Ready: Published Docker image with proper environment variable handling

✅ Developer Experience

  • VS Code Integration: Ready-to-use configurations for both local and Docker deployment
  • MCP Protocol: Full Model Context Protocol compliance for AI assistant integration
  • Type Safety: Complete TypeScript-style typing with Pydantic models
  • Testing: Comprehensive test suite with real API integration
  • Documentation: Extensive documentation with examples and best practices

Supported Categories

  • Linear: USDT perpetual, USDC perpetual, USDC futures
  • Inverse: Inverse perpetual, Inverse futures
  • Option: Options trading
  • Spot: Spot trading pairs

Testing

MCP Inspector

Test the server using the MCP inspector:

npx @modelcontextprotocol/inspector uv run bybit-mcp

Unit Tests

uv run pytest tests/

API Reference

Market Data Tools

All market data tools are always available and do not require special permissions.

Core Data

  • get_server_time: Get current Bybit server time
  • get_tickers: Get ticker information for symbols
  • get_order_book: Get order book depth
  • get_recent_trades: Get recent trade history

Kline/Candlestick Data

  • get_kline: Get standard OHLCV kline data
  • get_mark_price_kline: Get mark price historical data
  • get_index_price_kline: Get index price historical data
  • get_premium_index_price_kline: Get premium index kline data

Market Information

  • get_instruments_info: Get trading instrument details
  • get_funding_rate_history: Get funding rate history
  • get_open_interest: Get open interest statistics
  • get_insurance: Get insurance fund data
  • get_risk_limit: Get risk limit information
  • get_long_short_ratio: Get long/short ratio data

Trading Tools (Requires BYBIT_TRADING_ENABLED=true)

These tools are only available when trading is enabled via the BYBIT_TRADING_ENABLED environment variable.

Order Management

  • place_order: Place standard orders (Market, Limit) for immediate or specified price execution
  • place_trigger_order: Place conditional/trigger orders with advanced stop-loss, take-profit, and market entry strategies
  • amend_order: Modify existing pending orders (price, quantity, or trigger conditions)
  • cancel_order: Cancel a specific pending order
  • cancel_all_orders: Cancel all open orders for enhanced risk management

Batch Operations

  • batch_place_order: Place multiple orders in one request
  • batch_amend_order: Amend multiple orders in one request
  • batch_cancel_order: Cancel multiple orders in one request

Order Information

  • get_open_closed_orders: Get open and closed orders
  • get_order_history: Get order history
  • get_trade_history: Get trade execution history

Wallet & Account Management

  • get_wallet_balance: Get comprehensive wallet balance information
  • get_single_coin_balance: Get balance for a specific cryptocurrency
  • get_account_info: Get detailed account information and settings

Position Tools (Requires BYBIT_TRADING_ENABLED=true)

Position management tools require trading to be enabled.

Position Information

  • get_position_info: Query real-time position data
  • get_closed_pnl: Get closed profit and loss records

Position Configuration

  • set_leverage: Set position leverage
  • switch_cross_isolated_margin: Switch margin mode
  • switch_position_mode: Switch between one-way/hedge mode
  • set_auto_add_margin: Configure automatic margin addition

Risk Management

  • set_trading_stop: Set take profit, stop loss, trailing stops
  • modify_position_margin: Add or reduce position margin

Tools

All tools support the following common parameters where applicable:

  • category: Product type (linear, inverse, option, spot)
  • symbol: Trading symbol (e.g., BTCUSDT)
  • limit: Data size limit per page
  • start/end: Time range for historical data

Example Tool Calls

Get Server Time

{
  "name": "get_server_time",
  "arguments": {}
}

Get Ticker Data

{
  "name": "get_tickers",
  "arguments": {
    "category": "linear",
    "symbol": "BTCUSDT"
  }
}

Get Kline Data

{
  "name": "get_kline",
  "arguments": {
    "symbol": "BTCUSDT",
    "interval": "1",
    "category": "linear",
    "limit": 100
  }
}

Place Order (Requires Trading Enabled)

{
  "name": "place_order",
  "arguments": {
    "category": "linear",
    "symbol": "BTCUSDT",
    "side": "Buy",
    "orderType": "Limit",
    "qty": "0.001",
    "price": "50000.00",
    "orderLinkId": "my-order-123"
  }
}

Place Trigger Order (Requires Trading Enabled)

{
  "name": "place_trigger_order",
  "arguments": {
    "category": "linear",
    "symbol": "BTCUSDT",
    "side": "Buy",
    "orderType": "Market",
    "qty": "0.001",
    "triggerPrice": "48000.00",
    "triggerDirection": 2,
    "triggerBy": "LastPrice",
    "orderLinkId": "trigger-buy-123"
  }
}

Get Position Info (Requires Trading Enabled)

{
  "name": "get_position_info",
  "arguments": {
    "category": "linear",
    "symbol": "BTCUSDT"
  }
}

Set Leverage (Requires Trading Enabled)

{
  "name": "set_leverage",
  "arguments": {
    "category": "linear",
    "symbol": "BTCUSDT",
    "buyLeverage": "10",
    "sellLeverage": "10"
  }
}

Set Trading Stop (Requires Trading Enabled)

{
  "name": "set_trading_stop",
  "arguments": {
    "category": "linear",
    "symbol": "BTCUSDT",
    "takeProfit": "55000.00",
    "stopLoss": "45000.00",
    "positionIdx": 0
  }
}

Get Wallet Balance

{
  "name": "get_wallet_balance",
  "arguments": {
    "accountType": "UNIFIED",
    "coin": "USDT"
  }
}

Get Single Coin Balance

{
  "name": "get_single_coin_balance",
  "arguments": {
    "accountType": "UNIFIED",
    "coin": "BTC"
  }
}

Get Account Info

{
  "name": "get_account_info",
  "arguments": {}
}

Resources

  • bybit://market/info: General information about available endpoints and capabilities

Development

Project Structure

bybit-mcp/
├── src/bybit_mcp/
│   ├── __init__.py
│   ├── main.py              # MCP server implementation
│   ├── market.py            # Market data API functions
│   ├── trade.py             # Trading API functions
│   ├── position.py          # Position management functions
│   └── models/
│       ├── market_models.py # Market data Pydantic models
│       ├── trade_models.py  # Trading Pydantic models
│       └── position_models.py # Position Pydantic models
├── tests/
│   ├── test_market.py       # Market data unit tests
│   └── test_trade.py        # Trading unit tests
├── pyproject.toml           # Project configuration
├── Dockerfile               # Docker configuration
└── README.md

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Run the test suite
  6. Submit a pull request

Code Quality

The project uses:

  • Ruff: For linting and formatting
  • Pytest: For testing
  • Pydantic: For data validation
  • Type hints: For better code documentation

Recent Updates

v0.1.0 - Production Release

  • ✅ Complete Bybit v5 API coverage (market data, trading, positions, accounts)
  • ✅ Docker image published to falconiun/bybit-mcp
  • ✅ Fixed Pydantic validation issues (seq field type conversion)
  • ✅ Comprehensive VS Code MCP integration with working Docker configuration
  • ✅ Enhanced error handling and safety controls
  • ✅ Full wallet and account management support
  • ✅ Testnet support for safe development
  • ✅ Production-ready with comprehensive testing

License

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

Disclaimer

This software is for educational and development purposes. Always test thoroughly before using in production environments. The authors are not responsible for any financial losses incurred through the use of this software.

Support

For issues and questions:

  1. Check the existing GitHub Issues
  2. Create a new issue with detailed information
  3. Provide logs and error messages when applicable

Support the Project

If you find this MCP server useful for your trading and development needs, consider supporting its continued development:

Support on Patreon

ko-fi

Your support helps maintain and improve this project, add new features, and ensure compatibility with the latest Bybit API updates. Thank you for considering a contribution!

Acknowledgments