Bybit MCP Server
⚠️ TRADING WARNING ⚠️
This MCP server can execute REAL TRADING OPERATIONS on Bybit whenBYBIT_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
Installation
Prerequisites
- Python 3.13+
- uv package manager
Using uvx (Easiest - No Installation Required)
Run directly from PyPi without cloning or installing:
uvx bybit-mcp
Using uv (Recommended for local Development)
- Clone the repository:
git clone <repository-url>
cd bybit-mcp
- Install dependencies:
uv sync
- Set up environment variables:
# Copy the example environment file
cp .env.example .env
# Edit .env with your Bybit API credentials
BYBIT_API_KEY=your_api_key_here
BYBIT_API_SECRET=your_api_secret_here
BYBIT_TESTNET=false # Set to true for testnet
BYBIT_TRADING_ENABLED=false # Set to true to enable trading operations
- Run the server:
uv run bybit-mcp
Docker Usage
Build and Run
# Build the Docker image
docker build -t bybit-mcp .
# Run with environment variables (correct syntax)
docker run -i --rm --init \
-e BYBIT_API_KEY=your_api_key \
-e BYBIT_API_SECRET=your_api_secret \
-e BYBIT_TESTNET=false \
-e BYBIT_TRADING_ENABLED=false \
bybit-mcp
Using Docker Compose
# Set environment variables in .env file first
docker-compose up
Using Published Image
# Use the published Docker image
docker run -i --rm --init \
-e BYBIT_API_KEY=your_api_key \
-e BYBIT_API_SECRET=your_api_secret \
-e BYBIT_TESTNET=false \
-e BYBIT_TRADING_ENABLED=false \
falconiun/bybit-mcp
Configuration
Environment Variables
BYBIT_API_KEY: Your Bybit API keyBYBIT_API_SECRET: Your Bybit API secretBYBIT_TESTNET: Set totrueto use the Bybit testnet (default isfalse)BYBIT_TRADING_ENABLED: Set totrueto enable trading operations (default isfalse)
Safety Controls
The server implements several safety controls for trading operations:
Trading Disabled by Default
- All trading and position management tools are disabled by default
- Must explicitly set
BYBIT_TRADING_ENABLED=trueto enable trading - Market data tools are always available regardless of this setting
Testnet Support
- Set
BYBIT_TESTNET=trueto use Bybit's testnet environment - Recommended for development and testing
- Testnet trading uses fake money and won't affect real balances
Tool Visibility
- Trading tools only appear in the tool list when
BYBIT_TRADING_ENABLED=true - Position management tools require the same flag
- This prevents accidental trading operations
API Permissions
Ensure your Bybit API key has the appropriate permissions:
- Read-only: For market data (always safe)
- Trade: Required for order operations (enable only when needed)
- Position: Required for position management
- Withdraw: Not required for this server
MCP Client Integration
Claude Desktop
To use the Bybit MCP server with Claude Desktop, add the following configuration to your Claude Desktop MCP settings file:
Location of Claude Desktop MCP config:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Option 1: Using Published Docker Image (Recommended)
{
"mcpServers": {
"bybit-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--init",
"-e", "BYBIT_API_KEY=your_api_key_here",
"-e", "BYBIT_API_SECRET=your_api_secret_here",
"-e", "BYBIT_TESTNET=false",
"-e", "BYBIT_TRADING_ENABLED=false",
"falconiun/bybit-mcp"
]
}
}
}
Option 2: Using uvx (No Installation Required)
{
"mcpServers": {
"bybit-mcp": {
"command": "uvx",
"args": [
"bybit-mcp"
],
"env": {
"BYBIT_API_KEY": "your_api_key_here",
"BYBIT_API_SECRET": "your_api_secret_here",
"BYBIT_TESTNET": "false",
"BYBIT_TRADING_ENABLED": "false"
}
}
}
}
Option 3: Local Development
{
"mcpServers": {
"bybit-mcp": {
"command": "uv",
"args": ["run", "bybit-mcp"],
"cwd": "path/to/your/bybit-mcp",
"env": {
"BYBIT_API_KEY": "your_api_key_here",
"BYBIT_API_SECRET": "your_api_secret_here",
"BYBIT_TESTNET": "false",
"BYBIT_TRADING_ENABLED": "false"
}
}
}
}
Important Claude Desktop Notes:
- Replace
your_api_key_hereandyour_api_secret_herewith your actual Bybit API credentials - Set
BYBIT_TESTNET=truefor testing with fake money (recommended for first use) - Set
BYBIT_TRADING_ENABLED=trueonly when you want to enable real trading operations - Restart Claude Desktop after modifying the configuration file
Claude Desktop Usage Examples:
Once configured, you can ask Claude Desktop questions like:
- "What's my USDT balance?"
- "What's the current price of BTCUSDT?"
- "Show me the order book for ETHUSDT"
- "Get me the recent trading history for my account"
- "What positions do I currently have open?"
For trading (when BYBIT_TRADING_ENABLED=true):
- "Place a limit buy order for 0.001 BTC at $95,000"
- "Cancel all my open orders"
- "Set leverage to 10x for BTCUSDT"
- "Set a stop loss at $90,000 for my BTC position"
Security Best Practices:
- Start with
BYBIT_TESTNET=trueto test functionality safely - Use API keys with minimal required permissions (read-only for market data, trade permissions only when needed)
- Never share your configuration file containing API keys
- Consider using environment variables for sensitive credentials in production
Other MCP Clients
This server works with any MCP-compatible client. The configuration format may vary slightly between clients, but the core setup remains the same:
VS Code MCP Integration
Option 1: Local Development (Recommended)
Add to your VS Code settings.json:
{
"mcp": {
"servers": {
"bybit-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["bybit-mcp"],
"env": {
"BYBIT_API_KEY": "${input:bybit_api_key}",
"BYBIT_API_SECRET": "${input:bybit_api_secret}",
"BYBIT_TESTNET": "${input:bybit_testnet}",
"BYBIT_TRADING_ENABLED": "${input:bybit_trading_enabled}"
}
}
},
"inputs": [
{
"type": "promptString",
"id": "bybit_api_key",
"description": "Bybit API Key",
"password": true
},
{
"type": "promptString",
"id": "bybit_api_secret",
"description": "Bybit API Secret",
"password": true
},
{
"type": "promptString",
"id": "bybit_testnet",
"description": "Use Bybit Testnet",
"default": "false"
},
{
"type": "promptString",
"id": "bybit_trading_enabled",
"description": "Enable Bybit Trading",
"default": "false"
}
]
}
}
Option 2: Docker (Production)
For using the published Docker image:
{
"mcp": {
"servers": {
"bybit-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--init",
"-e",
"DOCKER_CONTAINER",
"-e",
"BYBIT_API_KEY",
"-e",
"BYBIT_API_SECRET",
"-e",
"BYBIT_TRADING_ENABLED",
"-e",
"BYBIT_TESTNET",
"falconiun/bybit-mcp"
],
"env": {
"DOCKER_CONTAINER": "true",
"BYBIT_API_KEY": "${input:bybit_api_key}",
"BYBIT_API_SECRET": "${input:bybit_api_secret}",
"BYBIT_TRADING_ENABLED": "${input:bybit_trading_enabled}",
"BYBIT_TESTNET": "${input:bybit_testnet}"
}
}
},
"inputs": [
{
"type": "promptString",
"id": "bybit_api_key",
"description": "Bybit API Key",
"password": true
},
{
"type": "promptString",
"id": "bybit_api_secret",
"description": "Bybit API Secret",
"password": true
},
{
"type": "promptString",
"id": "bybit_testnet",
"description": "Use Bybit Testnet",
"default": "false"
},
{
"type": "promptString",
"id": "bybit_trading_enabled",
"description": "Enable Bybit Trading",
"default": "false"
}
]
}
}
Important Docker Notes:
- The
-eflags are required to pass environment variables to the Docker container - The
envsection sets the variables in VS Code's environment, which are then passed to Docker - The
--initflag helps with proper signal handling in containers
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 timeget_tickers: Get ticker information for symbolsget_order_book: Get order book depthget_recent_trades: Get recent trade history
Kline/Candlestick Data
get_kline: Get standard OHLCV kline dataget_mark_price_kline: Get mark price historical dataget_index_price_kline: Get index price historical dataget_premium_index_price_kline: Get premium index kline data
Market Information
get_instruments_info: Get trading instrument detailsget_funding_rate_history: Get funding rate historyget_open_interest: Get open interest statisticsget_insurance: Get insurance fund dataget_risk_limit: Get risk limit informationget_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 executionplace_trigger_order: Place conditional/trigger orders with advanced stop-loss, take-profit, and market entry strategiesamend_order: Modify existing pending orders (price, quantity, or trigger conditions)cancel_order: Cancel a specific pending ordercancel_all_orders: Cancel all open orders for enhanced risk management
Batch Operations
batch_place_order: Place multiple orders in one requestbatch_amend_order: Amend multiple orders in one requestbatch_cancel_order: Cancel multiple orders in one request
Order Information
get_open_closed_orders: Get open and closed ordersget_order_history: Get order historyget_trade_history: Get trade execution history
Wallet & Account Management
get_wallet_balance: Get comprehensive wallet balance informationget_single_coin_balance: Get balance for a specific cryptocurrencyget_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 dataget_closed_pnl: Get closed profit and loss records
Position Configuration
set_leverage: Set position leverageswitch_cross_isolated_margin: Switch margin modeswitch_position_mode: Switch between one-way/hedge modeset_auto_add_margin: Configure automatic margin addition
Risk Management
set_trading_stop: Set take profit, stop loss, trailing stopsmodify_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 pagestart/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
Troubleshooting
Common Issues
Environment Variables Not Working in Docker
- Problem: API keys not being passed to Docker container
- Solution: Use the
-eflag format shown in the Docker configuration above - Note: The
envsection in VS Code MCP settings sets variables in VS Code's environment, which are then passed to Docker via-eflags
Pydantic Validation Errors
- Problem: Data type mismatches (e.g., integers vs strings)
- Solution: The server includes automatic type conversion for common API inconsistencies
- Example:
seqfield in trade history is automatically converted from int to string
Trading Operations Disabled
- Problem: Trading tools not appearing or returning disabled errors
- Solution: Set
BYBIT_TRADING_ENABLED=truein your environment variables - Safety: This is intentional - trading is disabled by default for safety
API Permission Errors
- Problem: 401 Unauthorized or insufficient permissions
- Solution: Verify your Bybit API key has the required permissions:
- Read-only: For market data (always safe)
- Trade: Required for order operations
- Position: Required for position management
Debug Mode
Enable debug logging by setting the log level:
# Local development
PYTHONPATH=src python -c "import logging; logging.basicConfig(level=logging.DEBUG)" -m bybit_mcp.main
# Docker
docker run -e PYTHONPATH=src -e LOG_LEVEL=DEBUG ...
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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Run the test suite
- 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:
- Check the existing GitHub Issues
- Create a new issue with detailed information
- 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:
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
- Built with the Model Context Protocol
- Uses the Bybit API v5
- Powered by pybit library