Bin MCP

🚀 币安MCP服务器

币安MCP服务器是一个模型上下文协议（MCP）服务器，它提供了对币安期货API端点的全面访问。该服务器实现了币安期货API文档中记录的所有主要交易、账户管理和市场数据功能。

🚀 快速开始

1. 安装包：

   pip install binance_futures_mcp
   

2. 运行服务器：

   uvx binance_futures_mcp --binance-api-key "your_key" --binance-secret-key "your_secret"
   

3. 在MCP客户端中进行配置（详细设置请参阅配置部分）

✨ 主要特性

• 11个重要交易工具，分为2个类别（账户信息和市场数据）
• 妥善的身份验证处理（拒绝未经身份验证的请求）
• 错误处理和优雅降级
• 实时市场数据访问

📦 安装指南

选项1：从PyPI安装（推荐）

从PyPI安装包：

pip install binance_futures_mcp

选项2：使用Docker部署

若要进行容器化部署：

# 克隆仓库
git clone https://github.com/alexcandrabersiva/bin-mcp.git
cd binance-mcp-server

# 构建Docker镜像
docker build -t binance-mcp-server .

# 使用环境变量运行
docker run -e BINANCE_API_KEY="your_api_key" -e BINANCE_SECRET_KEY="your_secret_key" \
  binance-mcp-server --binance-api-key "$BINANCE_API_KEY" --binance-secret-key "$BINANCE_SECRET_KEY"

使用Docker Compose（可选）

创建一个docker-compose.yml文件：

version: '3.8'
services:
  binance-mcp:
    build: .
    environment:
      - BINANCE_API_KEY=${BINANCE_API_KEY}
      - BINANCE_SECRET_KEY=${BINANCE_SECRET_KEY}
    command: [
      "--binance-api-key", "${BINANCE_API_KEY}",
      "--binance-secret-key", "${BINANCE_SECRET_KEY}"
    ]

然后运行：

docker-compose up

开发环境安装

若要进行开发，可以从源代码安装：

git clone https://github.com/bin-mcp/binance-mcp-server.git
cd binance-mcp-server
pip install -e ".[dev]"

⚙️ 配置

API权限要求

你的币安API密钥需要以下权限：

• 期货交易：用于下单和管理订单
• 期货读取：用于访问账户和市场数据

MCP客户端设置

该服务器可以与各种MCP客户端集成。以下是配置示例：

VS Code

在你的VS Code settings.json中添加以下内容：

{
  "mcp": {
    "servers": {
      "binance": {
        "command": "uvx",
        "args": ["--from", "binance_futures_mcp", "binance-mcp-server.exe", "--binance-api-key", "your_api_key", "--binance-secret-key", "your_secret_key"]
      }
    }
  }
}

Cursor

在你的Cursor配置文件（.cursor/mcp.json）中添加以下内容：

{
  "servers": {
    "binance": {
      "command": "uvx", 
      "args": ["--from", "binance_futures_mcp", "binance-mcp-server.exe", "--binance-api-key", "your_api_key", "--binance-secret-key", "your_secret_key"]
    }
  }
}

Windsurf

在你的Windsurf配置文件（.windsurf/mcp.json）中添加以下内容：

{
  "mcpServers": {
    "binance": {
      "command": "uvx",
      "args": ["--from", "binance_futures_mcp", "binance-mcp-server.exe", "--binance-api-key", "your_api_key", "--binance-secret-key", "your_secret_key"]
    }
  }
}

Claude Desktop

在你的Claude Desktop配置文件中添加以下内容：

在macOS上：~/Library/Application Support/Claude/claude_desktop_config.json
在Windows上：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "binance": {
      "command": "uvx",
      "args": ["--from", "binance_futures_mcp", "binance-mcp-server.exe", "--binance-api-key", "your_api_key", "--binance-secret-key", "your_secret_key"]
    }
  }
}

配置说明

1. 无需指定路径：通过PyPI安装时，无需指定路径或工作目录
2. 设置API凭证：将your_api_key和your_secret_key替换为你实际的币安API凭证
3. 替代命令：你也可以使用uvx binance_futures_mcp或python -m binance_mcp
4. 安全性：在生产环境中使用时，考虑将凭证存储在环境变量中

🛠️ 可用工具

服务器提供了11个重要工具，分为以下类别：

账户信息

(5个工具)

• get_account_info - 获取账户信息
• get_balance - 获取账户余额
• get_position_info - 获取持仓信息
• get_position_mode - 获取持仓模式（对冲 vs. 单向）
• get_commission_rate - 获取手续费率

市场数据

(6个工具)

• get_exchange_info - 获取交易所交易规则
• get_book_ticker - 获取订单簿上的最佳价格/数量
• get_price_ticker - 获取某个交易对的最新价格
• get_order_book - 获取订单簿深度
• get_klines - 获取K线数据
• get_mark_price - 获取标记价格和资金费率

💻 使用示例

下达市价订单

{
  "tool": "place_order",
  "arguments": {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "order_type": "MARKET",
    "quantity": 0.001
  }
}

下达限价订单

{
  "tool": "place_order",
  "arguments": {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "order_type": "LIMIT",
    "quantity": 0.001,
    "price": 50000.0,
    "time_in_force": "GTC"
  }
}

获取账户信息

{
  "tool": "get_account_info",
  "arguments": {}
}

获取市场数据

{
  "tool": "get_klines",
  "arguments": {
    "symbol": "BTCUSDT",
    "interval": "1h",
    "limit": 100
  }
}

获取24小时价格统计信息

{
  "tool": "get_24hr_ticker",
  "arguments": {
    "symbol": "BTCUSDT"
  }
}

获取 taker 买卖成交量比率

{
  "tool": "get_taker_buy_sell_volume",
  "arguments": {
    "symbol": "BTCUSDT"
  }
}

🔒 安全性

API密钥安全

🔐 你的币安API密钥和密钥机密完全保存在本地计算机上。MCP服务器完全在你的机器上运行，包作者或任何第三方远程服务都无法访问你的凭证。

密钥安全要点：

• ✅ 将凭证存储在环境变量（推荐）或本地配置文件中
• ✅ 除非你主动公开，否则密钥不会被传输
• ❌ 切勿将凭证提交到版本控制系统
• ❌ 切勿分享包含凭证的截图/日志
• ✅ 使用具有最小必要权限的API密钥
• ✅ 尽可能对密钥进行IP白名单设置
• ✅ 考虑在开发时使用币安测试网

工作原理：

1. 本地启动：你的编辑器/终端在本地启动MCP服务器：

   uvx binance_futures_mcp --binance-api-key $BINANCE_API_KEY --binance-secret-key $BINANCE_SECRET_KEY
   

2. 密钥本地保存：你的凭证仅存在于：

   • 你的环境变量或本地配置文件中
   • 你计算机的命令行/进程表中
   • 在向币安进行HTTPS调用期间的MCP进程内存中

3. 无遥测数据：该包中完全没有遥测或分析代码

速率限制和错误处理

• ⚡ 遵守币安基于权重的速率限制
• 🔄 自动对下单速率进行限制
• 🔐 自动生成HMAC SHA256签名
• 🛡️ 全面的错误处理，提供清晰的错误信息
• ✅ 在进行API调用之前进行参数验证

📚 详细文档

该服务器实现了币安期货API文档中记录的所有端点：

• 基础URL：https://fapi.binance.com
• API类型：币安USDT保证金期货
• 身份验证：API密钥 + HMAC SHA256签名
• 速率限制：自动遵守

有关详细的参数规范，请参阅币安期货API文档。

🔧 技术细节

项目结构

binance-mcp-server/
├── src/
│   └── binance_mcp/
│       ├── __init__.py          # 包初始化
│       ├── __main__.py          # CLI入口点
│       ├── server.py            # 主要的MCP服务器实现
│       ├── client.py            # 币安API客户端
│       ├── handlers.py          # 工具执行处理程序
│       ├── tools.py             # 工具定义（11个交易工具）
│       └── config.py            # 配置管理
├── Dockerfile                   # Docker容器化
├── .dockerignore               # Docker构建优化
├── pyproject.toml              # 项目配置
├── mcp-config.json             # MCP客户端配置示例
└── README.md                   # 文档

架构概述

• 模块化设计：多个组件之间职责分离
• 身份验证：通过环境变量安全处理API密钥
• 错误处理：优雅降级和全面的错误管理

运行测试

pytest

代码格式化

black src/
ruff check src/

❗ 错误代码

你可能会遇到的常见币安API错误代码：

完整列表请参阅币安API错误代码。

🤝 贡献

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 如有必要，添加测试
5. 提交拉取请求

📄 许可证

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

⚠️ 免责声明

⚠️ 重要提示：本软件仅用于教育和开发目的。交易加密货币涉及重大风险。请自行承担风险，切勿使用无法承受损失的资金进行交易。

💬 支持

如有问题和疑问：

• 查阅币安API文档
• 查看API文档中的错误代码
• 确保你的API凭证具有正确的权限