Built by Metorial, the integration platform for agentic AI.

Learn More

KYD.ai/mcp-server-bn

Binance Trading Server

    Server Summary

    • Execute spot trading operations (LIMIT/MARKET orders)

    • Monitor account balances

    • Track and manage open orders

    • Cancel existing orders

    • 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

    • Utilize advanced order types including trailing stops and reduce-only orders

mcp-server-cex-bn

smithery badge

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

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

  1. Clone the repository
  2. Install dependencies:
pnpm install
  1. Configure your Binance API credentials in .env
  2. 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-bn