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