mcp-server-cex-bn

mcp-server-cex-bn

此 MCP 服务可全面集成 Binance 的现货和期货交易操作。

中文说明

功能

现货交易操作

• 执行现货交易操作（LIMIT/MARKET 订单）
• 监控账户余额
• 跟踪和管理未完成订单
• 取消现有订单

期货交易操作

• 创建各种类型的期货订单（LIMIT、MARKET、STOP、TAKE_PROFIT 等）
• 管理杠杆设置（1-125x）
• 监控期货持仓和账户信息
• 跟踪资金费率
• 支持单向持仓和双向持仓模式
• 支持高级订单类型，包括追踪止损和仅减仓订单

工具

API 配置

configure_api_keys

安全地保存你的 Binance API 凭据：

await configureBinanceApiKeys({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});

现货交易工具

create_spot_order

创建 LIMIT 或 MARKET 订单：

// LIMIT order
await createSpotOrder({
  symbol: 'BTCUSDT',
  side: 'BUY',
  type: 'LIMIT',
  quantity: '0.001',
  price: '40000'
});

// MARKET order
await createSpotOrder({
  symbol: 'BTCUSDT',
  side: 'BUY',
  type: 'MARKET',
  quantity: '0.001'
});

cancel_order

取消现有订单：

await cancelOrder({
  symbol: 'BTCUSDT',
  orderId: '12345678'
});

get_balances

查看你的账户余额：

const balances = await getBalances();
// Returns: { BTC: '0.1', USDT: '1000', ... }

get_open_orders

列出所有未完成订单：

const orders = await getOpenOrders({
  symbol: 'BTCUSDT' // Optional: specify symbol
});

期货交易工具

create_futures_order

创建各种类型的期货订单：

// LIMIT order
await createFuturesOrder({
  symbol: 'BTCUSDT',
  side: 'BUY',
  type: 'LIMIT',
  quantity: '0.001',
  price: '40000',
  timeInForce: 'GTC'
});

// STOP MARKET order
await createFuturesOrder({
  symbol: 'BTCUSDT',
  side: 'SELL',
  type: 'STOP_MARKET',
  quantity: '0.001',
  stopPrice: '38000'
});

// TRAILING STOP order
await createFuturesOrder({
  symbol: 'BTCUSDT',
  side: 'SELL',
  type: 'TRAILING_STOP_MARKET',
  quantity: '0.001',
  callbackRate: '1.0' // 1% callback rate
});

set_futures_leverage

调整交易对的杠杆：

await setFuturesLeverage({
  symbol: 'BTCUSDT',
  leverage: 10  // 1-125x
});

get_futures_positions

获取所有未平仓期货持仓：

const positions = await getFuturesPositions();

get_futures_account

获取详细的期货账户信息：

const account = await getFuturesAccount();

get_funding_rate

获取期货交易对的资金费率：

const fundingRate = await getFundingRate({
  symbol: 'BTCUSDT'
});

cancel_futures_order

取消现有期货订单：

await cancelFuturesOrder({
  symbol: 'BTCUSDT',
  orderId: '12345678'
});

期货交易详情

持仓模式

• 单向模式：每个交易对只能有一个持仓
  • 默认模式，持仓管理更简单
  • 总持仓量为所有订单之和
• 双向持仓模式：多头和空头持仓分开管理
  • 支持同时持有多头和空头仓位
  • 每个持仓都有独立的保证金要求

保证金类型

• 逐仓保证金：每个持仓使用固定保证金
  • 风险仅限于分配的保证金
  • 每个持仓都有自己的杠杆设置
• 全仓保证金：多个持仓共享保证金
  • 资金利用效率更高
  • 所有持仓共享风险

资金费率

永续期货合约使用资金费率，使期货价格与现货价格保持一致：

• 费率为正：多头支付给空头
• 费率为负：空头支付给多头
• 每 8 小时支付一次

安全注意事项

现货交易安全

• 切勿将 API 密钥提交到版本控制系统
• 使用环境变量或安全的密钥存储方式
• 将 API 密钥权限限制为仅包含所需操作
• 定期轮换 API 密钥

期货交易安全

• 根据风险承受能力设置适当的杠杆上限
• 始终使用止损订单限制潜在损失
• 仔细监控强平价格
• 定期检查持仓风险和保证金率
• 考虑使用仅减仓订单来管理风险
• 使用全仓保证金时请谨慎，因为所有持仓共享风险

速率限制

• 遵守 Binance API 速率限制
• 默认速率限制：
  • 订单操作每分钟 1200 个请求
  • 行情数据每秒 100 个请求
• 为速率限制错误实现适当的错误处理

错误处理

常见错误情形

• API 凭据无效
• 余额或保证金不足
• 订单参数无效
• 超出速率限制
• 网络连接问题

期货特有错误

• InsufficientMarginError：操作所需保证金不足
• InvalidPositionModeError：持仓模式设置错误
• OrderValidationError：期货订单参数无效

错误处理示例：

try {
  await createFuturesOrder({
    symbol: 'BTCUSDT',
    side: 'BUY',
    type: 'LIMIT',
    quantity: '0.001',
    price: '40000',
    timeInForce: 'GTC'
  });
} catch (error) {
  if (error instanceof InsufficientMarginError) {
    console.error('Insufficient margin available');
  } else if (error instanceof InvalidPositionModeError) {
    console.error('Invalid position mode');
  } else if (error instanceof OrderValidationError) {
    console.error('Invalid order parameters');
  }
}

项目结构

.
├── src/
│   ├── index.ts                 # Server entry point
│   ├── services/
│   │   ├── binance.ts          # Binance API integration
│   │   ├── keystore.ts         # API key management
│   │   └── tools.ts            # Trading tools implementation
│   └── types/
│       ├── binance.ts          # Binance types
│       └── binance-connector.d.ts  # API client types
├── README.md
├── README_CN.md
├── package.json
├── pnpm-lock.yaml
└── tsconfig.json

开发

1. 设置环境变量：

在根目录中创建 .env 文件，并设置你的 Binance API 凭据：

BINANCE_API_KEY=your_api_key_here
BINANCE_API_SECRET=your_secret_key_here

2. 安装依赖：

pnpm install

构建服务：

pnpm build

开发时自动重新构建：

pnpm watch

安装

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 Binance Trading Server：

npx -y @smithery/cli install mcp-server-cex-bn --client claude

手动安装

1. 克隆仓库
2. 安装依赖：

pnpm install

3. 在 .env 中配置 Binance API 凭据
4. 构建并启动服务：

pnpm build
pnpm start

调试

由于 MCP 服务通过 stdio 通信，调试可能颇具挑战。我们建议使用 MCP Inspector，它可作为包脚本使用：

pnpm inspector

Inspector 会提供一个 URL，供你在浏览器中访问调试工具。

mcp-server-bn