Binance Trading Agent MCP Server

Binance Trading Agent (MCP)

A safety-first Model Context Protocol (MCP) server that connects any LLM client (Claude, Cursor, custom agents) to the Binance Spot API — with a hard focus on guardrails, testnet-first development, and auditable order flow.

<p> <img alt="status" src="https://img.shields.io/badge/status-Phase%201--done-brightgreen"> <img alt="protocol" src="https://img.shields.io/badge/protocol-MCP-blue"> <img alt="exchange" src="https://img.shields.io/badge/exchange-Binance%20Spot-f0b90b"> <img alt="safety" src="https://img.shields.io/badge/mode-testnet--first-green"> <img alt="license" src="https://img.shields.io/badge/license-MIT-lightgrey"> </p>

---

Phase 1 — Read-Only Tools

7 read-only MCP tools for reading market data and account info on Binance Spot Testnet.

| Tool | Type | Input | Purpose | |------|------|-------|---------| | get_spot_price | public | symbol | price, 24h change, bid/ask, high/low, volume | | get_klines | public | symbol, interval, limit | candlestick data | | get_order_book | public | symbol, limit | order book depth | | get_symbol_rules | public | symbol | minQty, stepSize, tickSize, minNotional | | get_account_balances | private | hideZero | free/locked balances, canTrade | | get_open_orders | private | symbol? | open orders | | get_trade_history | private | symbol, limit | recent trades |

Not in Phase 1: order placement/cancellation, futures, margin, OCO, websockets, autonomous actions.

Architecture

src/
  binance/            Layer 1 — Binance HTTP client
    client.ts         signedRequest / publicRequest, retry, timeout
    signing.ts        HMAC SHA256
    errors.ts         typed error classes
    rateLimiter.ts    weight tracking + backoff
    types.ts          response types
  services/           Layer 2 — domain services (normalization)
    marketDataService.ts
    accountService.ts
  tools/              Layer 3 — MCP tools (1 file = 1 tool)
    getSpotPrice.ts ... getTradeHistory.ts
  config.ts           .env validation (zod)
  logger.ts           structured JSON logging
  server.ts           MCP server registration
tests/
  unit/               signing, errors, rateLimiter, services, client

Getting started

# 1. Install
npm install

# 2. Configure (Binance Spot TESTNET keys)
cp .env.example .env
# Edit .env with your testnet keys

# 3. Run the MCP server
npm run dev

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "binance": {
      "command": "npx",
      "args": ["tsx", "/path/to/binance-trading-agent-mcp/src/server.ts"]
    }
  }
}

Connect to Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "binance": {
      "command": "npx",
      "args": ["tsx", "/path/to/binance-trading-agent-mcp/src/server.ts"]
    }
  }
}

Example tool calls

Get BTC price: `` tool: get_spot_price args: { "symbol": "BTCUSDT" } ``

Get 1h klines (last 100 candles): `` tool: get_klines args: { "symbol": "BTCUSDT", "interval": "1h", "limit": 100 } ``

Get order book (top 20 levels): `` tool: get_order_book args: { "symbol": "ETHUSDT", "limit": 20 } ``

Get symbol trading rules: `` tool: get_symbol_rules args: { "symbol": "BTCUSDT" } ``

Get account balances: `` tool: get_account_balances args: { "hideZero": true } ``

Get open orders: `` tool: get_open_orders args: { "symbol": "BTCUSDT" } ``

Get trade history: `` tool: get_trade_history args: { "symbol": "BTCUSDT", "limit": 50 } ``

Tests

# Run all unit tests
npm test

# Watch mode
npm run test:watch

Tech stack

• Language: TypeScript (Node 20+)
• Protocol: Model Context Protocol (MCP)
• Exchange API: Binance Spot REST
• Tooling: vitest, zod, pino

Roadmap

• [x] Phase 1 — Binance client + 7 read-only tools
• [ ] Phase 2 — Safe testnet trading: risk/policy layer, preview/place/cancel, full logging
• [ ] Phase 3 — Strategy design + backtesting on historical klines + paper trading
• [ ] Phase 4 — (optional) minimal real-money trading with strict limits
• [ ] Phase 5 — (optional) futures support

Disclaimer

This is engineering infrastructure, not financial advice. Automated trading with real funds carries real risk of loss. Use the Binance Testnet and dry_run mode by default. You are solely responsible for any keys, funds, strategy, and regulatory compliance in your jurisdiction.

License

MIT