SamerElhamdo/Binance-Futures-MCP-Server

📋 Table of Contents

• Overview
• Features
• Prerequisites
• Installation
• Configuration
• Available Tools
• Usage Examples
• Security
• Development
• API Documentation
• Contributing
• License

🎯 Overview

The Binance Futures MCP Server is a comprehensive Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Binance USDⓈ-M Futures API. With 14 powerful trading tools, you can manage your futures trading portfolio directly through conversational AI.

Key Highlights

• ✨ 14 Trading Tools - Complete futures trading functionality
• 🔒 Secure - HMAC SHA256 signature authentication
• 🚀 Fast - Optimized API calls with proper error handling
• 📊 Comprehensive - Order management, position tracking, and account monitoring
• 🎨 Easy to Use - Simple configuration and intuitive tool names

✨ Features

Core Trading Operations

• 📝 Order Management: Create, modify, query, and cancel orders
• 💼 Account Management: View balances, margins, and positions
• 📈 Position Control: Monitor and manage open positions
• ⚙️ Risk Management: Adjust leverage, margin types, and position modes

Advanced Capabilities

• 🔄 Order Modification: Update orders without canceling
• 📊 Trade History: View complete trading history
• 🎛️ Settings Management: Change leverage, position mode, and margin type
• 📋 Comprehensive Queries: Get all orders, open orders, and account details

📦 Prerequisites

Before you begin, ensure you have:

API Key Setup Checklist

• Create Binance API key
• Enable Futures trading permissions
• Copy API Key and Secret Key
• (Optional) Set IP whitelist restrictions
• (Recommended) Use read-only keys for testing

🚀 Installation

Quick Start (NPX)

npx -y binance-futures-mcp@latest

Install via NPM

npm install -g binance-futures-mcp

Install via Smithery

npx -y @smithery/cli install @smithery/binance-futures-mcp --client claude

⚙️ Configuration

Claude Desktop Configuration

# Create config file
touch "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

# Open in editor
open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
# OR using VS Code
code "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

# Open config file in VS Code
code %APPDATA%\Claude\claude_desktop_config.json

Configuration JSON

Add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "binance-futures-mcp": {
      "command": "npx",
      "args": ["-y", "binance-futures-mcp@latest"],
      "env": {
        "BINANCE_API_KEY": "your-api-key-here",
        "BINANCE_SECRET_KEY": "your-secret-key-here"
      }
    }
  }
}

Cline Configuration

# macOS
code ~/Library/Application\ Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

# Windows
code %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Then add the same configuration as above.

🛠️ Available Tools

📊 Complete Tools Table

📝 Detailed Tool Descriptions

{
  "symbol": "BTCUSDT",
  "side": "BUY",
  "type": "LIMIT",
  "quantity": 0.01,
  "price": 50000,
  "timeInForce": "GTC"
}

{
  "symbol": "BTCUSDT",
  "leverage": 10
}

{
  "symbol": "BTCUSDT",
  "amount": 100,
  "type": 1
}

💡 Usage Examples

Once configured, you can interact with Binance Futures through Claude:

Conversational Commands

"Check my Binance Futures account balance"
"Create a limit buy order for 0.01 BTCUSDT at $50,000"
"Show me all my open positions"
"Cancel all open orders for BTCUSDT"
"What's the status of order ID 12345?"
"Change leverage for BTCUSDT to 10x"
"Get my trade history for the last 24 hours"
"Modify order 12345 to new price $51,000"

Example Workflows

1. Create and Monitor Order:

   • Create a LIMIT order
   • Query order status
   • Modify if needed
   • Monitor execution

2. Risk Management:

   • Check account balance
   • View open positions
   • Adjust leverage
   • Modify margin if needed

3. Position Analysis:

   • Get all positions
   • View trade history
   • Analyze PnL

🔒 Security Considerations

Best Practices

Security Checklist

• API keys stored in environment variables only
• Secret key never exposed in logs or errors
• Read-only keys used for testing
• IP whitelist configured (if available)
• API key permissions minimized
• .env file in .gitignore
• Keys not committed to version control

💻 Development

Installation from Source

# Clone repository
git clone https://github.com/SamerElhamdo/Binance-Futures-MCP-Server.git
cd Binance-Futures-MCP-Server

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

Project Structure

Binance-Futures-MCP-Server/
├── src/
│   └── index.ts          # Main server implementation
├── build/
│   └── index.js          # Compiled JavaScript
├── package.json           # Project configuration
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Available Scripts

Environment Variables

Create a .env file in the project root:

BINANCE_API_KEY=your-api-key-here
BINANCE_SECRET_KEY=your-secret-key-here

📚 API Documentation

This MCP server uses the official Binance USDⓈ-M Futures API.

Key Endpoints

Error Handling

The server provides detailed error messages from Binance API:

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Contribution Guidelines

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Model Context Protocol - For the MCP specification
• Anthropic - For Claude Desktop
• Binance - For the Futures API
• All contributors and users of this project