trading-platform/apps/mcp-binance-connector

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 library for Binance API integration.

---

Installation

# 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

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

# Development (with hot reload)
npm run dev

# Production
npm run build
npm start

Health Check

curl http://localhost:3606/health

List Available Tools

curl http://localhost:3606/tools

Execute a Tool

# 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

npm run build

Type Check

npm run typecheck

Lint

npm run lint
npm run lint:fix

Test

npm run test
npm run test:coverage

---

Docker

Build Image

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

Run Container

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:

{
  "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
2. Go to API Management
3. Create a new API key
4. Enable Spot Trading permissions
5. (Optional) For testnet: Binance Testnet

---

Troubleshooting

Cannot connect to Binance

# 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

# 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
• CCXT Documentation
• Binance API
• 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