# 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

```bash
# 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`:

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

### Connect to Cursor

Add to `.cursor/mcp.json`:

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

```bash
# 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