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憑證具有正確的權限