trading-platform-mcp-binance-connector-v2/README.md

# MCP Binance Connector

**Version:** 1.0.0
**Date:** 2026-01-04
**System:** Trading Platform + NEXUS v3.4 + SIMCO

---

## Description

MCP Server that exposes Binance cryptocurrency exchange capabilities as tools for AI agents. This service enables AI agents to:

- Query market data (prices, order books, candles)
- Monitor account balances
- View and manage open orders
- Execute trades (buy/sell with market, limit, stop orders)

Uses [CCXT](https://github.com/ccxt/ccxt) library for Binance API integration.

---

## Installation

```bash
# Navigate to the project
cd /home/isem/workspace-v1/projects/trading-platform/apps/mcp-binance-connector

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your Binance API credentials
```

---

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | MCP Server port | 3606 |
| `MCP_API_KEY` | API key for MCP authentication | - |
| `BINANCE_API_KEY` | Binance API key | - |
| `BINANCE_API_SECRET` | Binance API secret | - |
| `BINANCE_TESTNET` | Use Binance testnet | true |
| `MAX_ORDER_VALUE_USDT` | Max order value limit | 1000 |
| `MAX_DAILY_VOLUME_USDT` | Max daily trading volume | 10000 |
| `MAX_LEVERAGE` | Max leverage allowed | 20 |
| `LOG_LEVEL` | Logging level | info |

### Example .env

```env
PORT=3606
BINANCE_API_KEY=your_api_key_here
BINANCE_API_SECRET=your_api_secret_here
BINANCE_TESTNET=true
MAX_ORDER_VALUE_USDT=1000
MAX_DAILY_VOLUME_USDT=10000
LOG_LEVEL=info
```

---

## Usage

### Start Server

```bash
# Development (with hot reload)
npm run dev

# Production
npm run build
npm start
```

### Health Check

```bash
curl http://localhost:3606/health
```

### List Available Tools

```bash
curl http://localhost:3606/tools
```

### Execute a Tool

```bash
# Get BTC price
curl -X POST http://localhost:3606/tools/binance_get_ticker \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"symbol": "BTCUSDT"}}'

# Get order book
curl -X POST http://localhost:3606/tools/binance_get_orderbook \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"symbol": "ETHUSDT", "limit": 10}}'

# Get candlestick data
curl -X POST http://localhost:3606/tools/binance_get_klines \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"symbol": "BTCUSDT", "interval": "1h", "limit": 24}}'

# Get account balance (requires API keys)
curl -X POST http://localhost:3606/tools/binance_get_account \
  -H "Content-Type: application/json" \
  -d '{"parameters": {}}'

# Create order (requires API keys) - HIGH RISK
curl -X POST http://localhost:3606/tools/binance_create_order \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"symbol": "BTCUSDT", "side": "buy", "type": "market", "amount": 0.001}}'
```

---

## MCP Tools Available

| Tool | Description | Risk Level |
|------|-------------|------------|
| `binance_get_ticker` | Get current price and 24h stats | LOW |
| `binance_get_orderbook` | Get order book depth | LOW |
| `binance_get_klines` | Get OHLCV candles | LOW |
| `binance_get_account` | Get account balances | MEDIUM |
| `binance_get_open_orders` | List open orders | MEDIUM |
| `binance_create_order` | Create buy/sell order | HIGH (*) |
| `binance_cancel_order` | Cancel pending order | MEDIUM |

(*) Tools marked with HIGH risk require explicit confirmation and pass through risk checks.

---

## Project Structure

```
mcp-binance-connector/
├── README.md                 # This file
├── package.json              # Dependencies
├── tsconfig.json             # TypeScript configuration
├── .env.example              # Environment template
├── Dockerfile                # Container configuration
└── src/
    ├── index.ts              # Server entry point
    ├── config.ts             # Configuration management
    ├── utils/
    │   └── logger.ts         # Winston logger
    ├── services/
    │   └── binance-client.ts # CCXT wrapper
    ├── middleware/
    │   └── risk-check.ts     # Pre-trade risk validation
    └── tools/
        ├── index.ts          # Tool registry
        ├── market.ts         # Market data tools
        ├── account.ts        # Account tools
        └── orders.ts         # Order management tools
```

---

## Development

### Build

```bash
npm run build
```

### Type Check

```bash
npm run typecheck
```

### Lint

```bash
npm run lint
npm run lint:fix
```

### Test

```bash
npm run test
npm run test:coverage
```

---

## Docker

### Build Image

```bash
docker build -t mcp-binance-connector:1.0.0 .
```

### Run Container

```bash
docker run -d \
  --name mcp-binance-connector \
  -p 3606:3606 \
  -e BINANCE_API_KEY=your_key \
  -e BINANCE_API_SECRET=your_secret \
  -e BINANCE_TESTNET=true \
  mcp-binance-connector:1.0.0
```

---

## Integration with Claude

### MCP Configuration

Add to your Claude/MCP configuration:

```json
{
  "mcpServers": {
    "binance": {
      "url": "http://localhost:3606",
      "transport": "http"
    }
  }
}
```

### Example Agent Prompts

```
"What's the current Bitcoin price?"
  -> Uses binance_get_ticker({ symbol: "BTCUSDT" })

"Show me the ETH order book"
  -> Uses binance_get_orderbook({ symbol: "ETHUSDT" })

"Get the last 50 hourly candles for BTC"
  -> Uses binance_get_klines({ symbol: "BTCUSDT", interval: "1h", limit: 50 })

"Check my Binance balance"
  -> Uses binance_get_account()

"Buy 0.01 BTC at market price"
  -> Uses binance_create_order({ symbol: "BTCUSDT", side: "buy", type: "market", amount: 0.01 })
```

---

## Risk Management

The connector includes built-in risk checks:

1. **Maximum Order Value**: Orders exceeding `MAX_ORDER_VALUE_USDT` are rejected
2. **Daily Volume Limit**: Trading stops when `MAX_DAILY_VOLUME_USDT` is reached
3. **Balance Check**: Buy orders verify sufficient balance
4. **Testnet Default**: Testnet is enabled by default for safety
5. **High-Risk Confirmation**: Orders require explicit confirmation flag

---

## Dependencies

### Runtime
- `express` - HTTP server
- `ccxt` - Cryptocurrency exchange library
- `zod` - Input validation
- `winston` - Logging
- `dotenv` - Environment configuration
- `@modelcontextprotocol/sdk` - MCP protocol

### Development
- `typescript` - Type safety
- `ts-node-dev` - Development server
- `jest` - Testing framework
- `eslint` - Code linting

---

## Prerequisites

1. **Binance Account** with API keys (optional for public data)
2. **Testnet API Keys** for testing (recommended)
3. **Node.js** >= 20.0.0

### Getting Binance API Keys

1. Log into [Binance](https://www.binance.com)
2. Go to API Management
3. Create a new API key
4. Enable Spot Trading permissions
5. (Optional) For testnet: [Binance Testnet](https://testnet.binance.vision/)

---

## Troubleshooting

### Cannot connect to Binance

```bash
# Check connectivity
curl https://api.binance.com/api/v3/ping

# If using testnet, check testnet connectivity
curl https://testnet.binance.vision/api/v3/ping
```

### Authentication errors

```bash
# Verify API keys are set
cat .env | grep BINANCE

# Check health endpoint for config status
curl http://localhost:3606/health
```

### Order rejected by risk check

The order may exceed configured limits. Check:
- `MAX_ORDER_VALUE_USDT` - single order limit
- `MAX_DAILY_VOLUME_USDT` - daily trading limit
- Available balance for buy orders

---

## References

- [MCP Protocol](https://modelcontextprotocol.io)
- [CCXT Documentation](https://docs.ccxt.com)
- [Binance API](https://binance-docs.github.io/apidocs/)
- Architecture: `/docs/01-arquitectura/MCP-BINANCE-CONNECTOR-SPEC.md`
- MT4 Connector: `/apps/mcp-mt4-connector/` (reference implementation)

---

**Maintained by:** @PERFIL_MCP_DEVELOPER
**Project:** Trading Platform