mcp-server-cex-bn

This MCP Server provides comprehensive integration with Binance's spot and futures trading operations.

中文说明

Features

Spot Trading Operations

Execute spot trading operations (LIMIT/MARKET orders)
Monitor account balances
Track and manage open orders
Cancel existing orders

Futures Trading Operations

Create various types of futures orders (LIMIT, MARKET, STOP, TAKE_PROFIT, etc.)
Manage leverage settings (1-125x)
Monitor futures positions and account information
Track funding rates
Support for both one-way and hedge mode positions
Advanced order types including trailing stops and reduce-only orders

Tools

API Configuration

`configure_api_keys`

Securely store your Binance API credentials:

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

Spot Trading Tools

`create_spot_order`

Create LIMIT or MARKET orders:

// 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`

Cancel an existing order:

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

`get_balances`

Check your account balances:

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

`get_open_orders`

List all open orders:

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

Futures Trading Tools

`create_futures_order`

Create various types of futures orders:

// 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`

Adjust leverage for a trading pair:

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

`get_futures_positions`

Get all open futures positions:

const positions = await getFuturesPositions();

`get_futures_account`

Get detailed futures account information:

const account = await getFuturesAccount();

`get_funding_rate`

Get funding rate for a futures symbol:

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

`cancel_futures_order`

Cancel an existing futures order:

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

Futures Trading Details

Position Modes

One-way Mode: Single position per symbol
- Default mode, simpler position management
- Total position size is the sum of all orders
Hedge Mode: Separate long and short positions
- Allows holding both long and short positions simultaneously
- Each position has independent margin requirements

Margin Types

Isolated Margin: Fixed margin per position
- Risk is limited to the allocated margin
- Each position has its own leverage setting
Cross Margin: Shared margin across positions
- Higher capital efficiency
- Shared risk across all positions

Funding Rate

Perpetual futures contracts use funding rates to keep futures prices aligned with spot prices:

Positive rate: Longs pay shorts
Negative rate: Shorts pay longs
Payments occur every 8 hours

Security Considerations

Spot Trading Security

Never commit API keys to version control
Use environment variables or secure key storage
Restrict API key permissions to only required operations
Regularly rotate your API keys

Futures Trading Security

Set appropriate leverage limits based on risk tolerance
Always use stop-loss orders to limit potential losses
Monitor liquidation prices carefully
Regularly check position risks and margin ratios
Consider using reduce-only orders for risk management
Be cautious with cross-margin due to shared risk

Rate Limits

Respect Binance API rate limits
Default rate limits:
- 1200 requests per minute for order operations
- 100 requests per second for market data
Implement proper error handling for rate limit errors

Error Handling

Common Error Scenarios

Invalid API credentials
Insufficient balance or margin
Invalid order parameters
Rate limit exceeded
Network connectivity issues

Futures-Specific Errors

InsufficientMarginError: Not enough margin for operation
InvalidPositionModeError: Wrong position mode setting
OrderValidationError: Invalid futures order parameters

Example error handling:

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');
  }
}

Project Structure

.
├── 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

Development

Set up environment variables:

create .env file in the root directory, and set your Binance API credentials:

BINANCE_API_KEY=your_api_key_here
BINANCE_API_SECRET=your_secret_key_here

Install dependencies:

pnpm install

Build the server:

pnpm build

For development with auto-rebuild:

pnpm watch

Installation

Installing via Smithery

To install Binance Trading Server for Claude Desktop automatically via Smithery:

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

Installing manually

Clone the repository
Install dependencies:

pnpm install

Configure your Binance API credentials in .env
Build and start the server:

pnpm build
pnpm start

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

pnpm inspector

The Inspector will provide a URL to access debugging tools in your browser.

MCP Server for Binance Spot Trading