Bybit Mcp Full

Bybit MCP 服务

⚠️ 交易警告 ⚠️
当 BYBIT_TRADING_ENABLED=true 时，此 MCP 服务可以在 Bybit 上执行真实交易操作。
交易操作会使用真实资金，并可能导致财务损失。
启用交易前，请务必先在测试网（BYBIT_TESTNET=true）上进行测试，并了解相关风险。
为确保安全，交易功能默认处于禁用状态。

一个全面的模型上下文协议（MCP）服务，可完全访问 Bybit 的 v5 API。此服务可让 AI 助手从 Bybit 加密货币交易所获取实时市场数据、执行交易操作、管理持仓并访问账户信息。

🚀 可用于生产环境

✅ 经过全面测试 — 所有端点均已测试且可正常工作
✅ 支持 Docker — 已发布的镜像位于 falconiun/bybit-mcp
✅ 集成 VS Code — 提供可直接使用的配置
✅ 全面覆盖 API — 市场数据、交易、持仓和账户管理

功能

核心市场数据

• 服务器时间：获取当前 Bybit 服务器时间
• 行情：获取交易品种的行情信息
• 订单簿：获取任意交易品种的订单簿深度
• 近期成交：查看近期交易历史

K 线／蜡烛图数据

• 标准 K 线：获取 OHLCV 蜡烛图数据
• 标记价格 K 线：获取标记价格历史数据
• 指数价格 K 线：获取指数价格历史数据
• 溢价指数 K 线：获取溢价指数价格数据

交易信息

• 交易品种信息：获取详细的交易品种信息
• 资金费率历史：查看历史资金费率
• 未平仓合约量：获取未平仓合约量统计数据
• 风险限额：获取风险限额信息

市场统计数据

• 保险基金：获取保险基金数据
• 多空比：查看多空比统计数据

交易操作（需要设置 BYBIT_TRADING_ENABLED=true）

• 订单管理：全面控制订单的下单、修改和取消
• 高级订单类型：支持市价单、限价单和条件／触发单
• 批量操作：通过单个请求执行多个订单，提高效率
• 订单历史：查看全面的未结／已结订单和交易历史
• 实时执行：即时获取订单状态和成交情况
• 触发单：支持价格触发条件以及高级止盈／止损逻辑的条件单

持仓管理（需要设置 BYBIT_TRADING_ENABLED=true）

• 持仓信息：查询实时持仓数据及详细指标
• 杠杆控制：动态设置和调整持仓杠杆
• 保证金管理：在全仓／逐仓保证金模式之间切换
• 交易止损：设置止盈、止损和追踪止损
• 自动追加保证金：配置自动追加保证金
• 持仓模式：在单向持仓和双向持仓模式之间切换
• 盈亏追踪：查看已平仓盈亏记录

账户与钱包管理

• 钱包余额：获取全面的钱包余额信息
• 单币种余额：查询指定币种的余额
• 账户信息：查看详细的账户信息和设置
• 多种账户类型：支持 UNIFIED、CONTRACT、SPOT、INVESTMENT 账户

🎯 核心能力

✅ 完整覆盖 API

• 市场数据：覆盖所有 Bybit v5 市场端点（行情、订单簿、K 线、资金费率等）
• 交易：完整的订单生命周期管理（下单、修改、取消、批量操作）
• 高级订单：支持条件／触发单，可实现复杂的入场和退出策略
• 持仓：完整的持仓管理（杠杆、保证金、止损、盈亏追踪）
• 账户：钱包余额、账户信息和多账户支持

✅ 为 Agent 优化的设计

• 清晰的工具描述：每个工具都提供详细且便于 Agent 理解的描述，说明其用途和使用方法
• 丰富的参数架构：全面的 JSON 架构，包含示例、枚举值和验证约束
• 安全警告：重要的交易工具包含醒目的安全警告和风险提示
• 使用指南：工具提供关于何时以及如何有效使用的上下文信息
• 错误预防：架构验证会在 API 调用前避免常见的参数错误

✅ 生产环境功能

• 安全优先：交易默认禁用，必须显式启用
• 测试网支持：全面集成测试网，便于安全地开发和测试
• 错误处理：全面的错误处理，并提供详细的错误消息
• 数据验证：Pydantic 模型确保数据完整性和类型安全
• 支持 Docker：已发布 Docker 镜像，并妥善处理环境变量

✅ 开发者体验

• VS Code 集成：提供可直接使用的本地和 Docker 部署配置
• MCP 协议：完全符合 Model Context Protocol，支持与 AI 助手集成
• 类型安全：通过 Pydantic 模型实现完整的 TypeScript 风格类型标注
• 测试：全面的测试套件，包含真实 API 集成
• 文档：详尽的文档，包含示例和最佳实践

支持的类别

• Linear：USDT 永续合约、USDC 永续合约、USDC 期货
• Inverse：反向永续合约、反向期货
• Option：期权交易
• Spot：现货交易对

安装

前置条件

• Python 3.13+
• uv 包管理器

使用 uvx（最简单，无需安装）

无需克隆或安装，即可直接从 PyPi 运行：

uvx bybit-mcp

使用 uv（推荐用于本地开发）

1. 克隆仓库：

git clone <repository-url>
cd bybit-mcp

2. 安装依赖：

uv sync

3. 设置环境变量：

# 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

4. 运行服务：

uv run bybit-mcp

Docker 用法

构建并运行

# 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

使用 Docker Compose

# Set environment variables in .env file first
docker-compose up

使用已发布的镜像

# 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

配置

环境变量

• BYBIT_API_KEY：你的 Bybit API 密钥
• BYBIT_API_SECRET：你的 Bybit API 密钥 Secret
• BYBIT_TESTNET：设为 true 以使用 Bybit 测试网（默认为 false）
• BYBIT_TRADING_ENABLED：设为 true 以启用交易操作（默认为 false）

安全控制

该服务针对交易操作实施了多项安全控制：

默认禁用交易

• 所有交易和持仓管理工具默认禁用
• 必须显式设置 BYBIT_TRADING_ENABLED=true 才能启用交易
• 无论此设置如何，市场数据工具始终可用

测试网支持

• 设置 BYBIT_TESTNET=true 以使用 Bybit 的测试网环境
• 推荐用于开发和测试
• 测试网交易使用虚拟资金，不会影响真实余额

工具可见性

• 仅当 BYBIT_TRADING_ENABLED=true 时，交易工具才会显示在工具列表中
• 持仓管理工具也需要启用同一标志
• 这样可防止意外的交易操作

API 权限

确保你的 Bybit API 密钥具有相应权限：

• 只读：用于市场数据（始终安全）
• 交易：下单操作所需（仅在需要时启用）
• 持仓：持仓管理所需
• 提现：此服务不需要

MCP 客户端集成

Claude Desktop

要在 Claude Desktop 中使用 Bybit MCP 服务，请将以下配置添加到 Claude Desktop MCP 设置文件中：

Claude Desktop MCP 配置文件位置：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

选项 1：使用已发布的 Docker 镜像（推荐）

{
  "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"
      ]
    }
  }
}

选项 2：使用 uvx（无需安装）

{
  "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"
      }
    }
  }
}

选项 3：本地开发

{
  "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"
      }
    }
  }
}

Claude Desktop 重要说明：

• 将 your_api_key_here 和 your_api_secret_here 替换为你实际的 Bybit API 凭据
• 设置 BYBIT_TESTNET=true，使用模拟资金进行测试（首次使用时推荐）
• 仅当你想启用真实交易操作时，才设置 BYBIT_TRADING_ENABLED=true
• 修改配置文件后，重启 Claude Desktop

Claude Desktop 使用示例：

配置完成后，你可以向 Claude Desktop 提问，例如：

• “我的 USDT 余额是多少？”
• “BTCUSDT 的当前价格是多少？”
• “显示 ETHUSDT 的订单簿”
• “获取我账户最近的交易历史”
• “我目前有哪些未平仓仓位？”

交易相关（当 BYBIT_TRADING_ENABLED=true 时）：

• “以 $95,000 的价格为 0.001 BTC 下限价买单”
• “取消我所有未完成的订单”
• “将 BTCUSDT 的杠杆设置为 10x”
• “为我的 BTC 仓位设置 $90,000 的止损价”

安全最佳实践：

• 从 BYBIT_TESTNET=true 开始，安全地测试功能
• 使用仅具备最低所需权限的 API 密钥（市场数据使用只读权限，仅在需要时授予交易权限）
• 切勿分享包含 API 密钥的配置文件
• 在生产环境中，可考虑使用环境变量存储敏感凭据

其他 MCP 客户端

此服务适用于任何兼容 MCP 的客户端。不同客户端的配置格式可能略有不同，但核心设置保持不变：

VS Code MCP 集成

选项 1：本地开发（推荐）

将以下内容添加到 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"
      }
    ]
  }
}

选项 2：Docker（生产环境）

如需使用已发布的 Docker 镜像：

{
  "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"
      }
    ]
  }
}

Docker 重要说明：

• 需要使用 -e 标志将环境变量传递给 Docker 容器
• env 部分在 VS Code 环境中设置变量，然后将这些变量传递给 Docker
• --init 标志有助于容器正确处理信号

测试

MCP Inspector

使用 MCP Inspector 测试服务：

npx @modelcontextprotocol/inspector uv run bybit-mcp

单元测试

uv run pytest tests/

API 参考

市场数据工具

所有市场数据工具始终可用，无需特殊权限。

核心数据

• get_server_time：获取 Bybit 服务的当前时间
• get_tickers：获取各交易品种的行情信息
• get_order_book：获取订单簿深度
• get_recent_trades：获取近期交易历史

K 线/蜡烛图数据

• get_kline：获取标准 OHLCV K 线数据
• get_mark_price_kline：获取标记价格历史数据
• get_index_price_kline：获取指数价格历史数据
• get_premium_index_price_kline：获取溢价指数 K 线数据

市场信息

• get_instruments_info：获取交易品种详情
• get_funding_rate_history：获取资金费率历史
• get_open_interest：获取未平仓量统计数据
• get_insurance：获取保险基金数据
• get_risk_limit：获取风险限额信息
• get_long_short_ratio：获取多空比数据

交易工具（需要 BYBIT_TRADING_ENABLED=true）

仅当通过 BYBIT_TRADING_ENABLED 环境变量启用交易时，这些工具才可用。

订单管理

• place_order：下达标准订单（Market、Limit），立即执行或按指定价格执行
• place_trigger_order：下达条件单／触发单，支持高级止损、止盈和市价入场策略
• amend_order：修改现有挂单（价格、数量或触发条件）
• cancel_order：取消指定挂单
• cancel_all_orders：取消所有未结订单，以加强风险管理

批量操作

• batch_place_order：通过单个请求下达多个订单
• batch_amend_order：通过单个请求修改多个订单
• batch_cancel_order：通过单个请求取消多个订单

订单信息

• get_open_closed_orders：获取未结和已结订单
• get_order_history：获取订单历史记录
• get_trade_history：获取交易执行历史记录

钱包与账户管理

• get_wallet_balance：获取完整的钱包余额信息
• get_single_coin_balance：获取指定加密货币的余额
• get_account_info：获取详细的账户信息和设置

持仓工具（需要设置 BYBIT_TRADING_ENABLED=true）

使用持仓管理工具需要启用交易功能。

持仓信息

• get_position_info：查询实时持仓数据
• get_closed_pnl：获取已平仓的盈亏记录

持仓配置

• set_leverage：设置持仓杠杆
• switch_cross_isolated_margin：切换保证金模式
• switch_position_mode：在单向模式和对冲模式之间切换
• set_auto_add_margin：配置自动追加保证金

风险管理

• set_trading_stop：设置止盈、止损和跟踪止损
• modify_position_margin：增加或减少持仓保证金

工具

所有工具均支持以下通用参数（如适用）：

• category：产品类型（linear、inverse、option、spot）
• symbol：交易代码（例如，BTCUSDT）
• limit：每页数据量上限
• start/end：历史数据的时间范围

工具调用示例

获取服务器时间

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

获取行情数据

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

获取 K 线数据

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

下达订单（需要启用交易）

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

下达触发单（需要启用交易）

{
  "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"
  }
}

获取持仓信息（需要启用交易）

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

设置杠杆（需要启用交易）

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

设置交易止损（需要启用交易）

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

获取钱包余额

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

获取单种货币余额

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

获取账户信息

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

资源

• bybit://market/info：有关可用端点和功能的一般信息

故障排除

常见问题

Docker 中的环境变量未生效

• 问题：API 密钥未传递到 Docker 容器
• 解决方案：使用上述 Docker 配置中所示的 -e 标志格式
• 注意：VS Code MCP 设置中的 env 部分会在 VS Code 的环境中设置变量，随后通过 -e 标志将其传递给 Docker

Pydantic 验证错误

• 问题：数据类型不匹配（例如，整数与字符串不匹配）
• 解决方案：服务包含针对常见 API 不一致情况的自动类型转换
• 示例：交易历史记录中的 seq 字段会自动从整数转换为字符串

交易操作已禁用

• 问题：交易工具未显示或返回已禁用错误
• 解决方案：在环境变量中设置 BYBIT_TRADING_ENABLED=true
• 安全性：这是有意为之——为了安全起见，默认禁用交易

API 权限错误

• 问题：401 未授权或权限不足
• 解决方案：确认你的 Bybit API 密钥具有所需权限：
  • 只读：用于行情数据（始终安全）
  • 交易：下单操作所需
  • 持仓：持仓管理所需

调试模式

通过设置日志级别启用调试日志：

# 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 ...

开发

项目结构

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

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行修改
4. 为新功能添加测试
5. 运行测试套件
6. 提交 pull request

代码质量

本项目使用：

• Ruff：用于代码检查和格式化
• Pytest：用于测试
• Pydantic：用于数据验证
• 类型提示：用于更好地说明代码

最新更新

v0.1.0 - 正式版

• ✅ 完整覆盖 Bybit v5 API（市场数据、交易、持仓、账户）
• ✅ Docker 镜像已发布至 falconiun/bybit-mcp
• ✅ 修复 Pydantic 验证问题（seq 字段类型转换）
• ✅ 完善 VS Code MCP 集成，并提供可用的 Docker 配置
• ✅ 增强错误处理和安全控制
• ✅ 完整支持钱包和账户管理
• ✅ 支持测试网，便于安全开发
• ✅ 已做好生产环境部署准备，并经过全面测试

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

免责声明

本软件仅用于教育和开发目的。在生产环境中使用前，请务必进行充分测试。作者不对因使用本软件而造成的任何财务损失负责。

支持

如有问题，请：

1. 查看现有的 GitHub Issues
2. 创建新 issue 并提供详细信息
3. 适用时提供日志和错误消息

支持本项目

如果你发现此 MCP 服务对你的交易和开发有帮助，可以考虑支持本项目的持续开发：

你的支持有助于维护和改进本项目、添加新功能，并确保与最新的 Bybit API 更新兼容。感谢你考虑为本项目提供支持！

致谢

• 基于 Model Context Protocol 构建
• 使用 Bybit API v5
• 由 pybit 库提供支持