premium-futures-mcp 1.5.1

Premium Binance Futures MCP Server - Advanced trading tools for professional traders

Premium Binance Futures MCP Server

Advanced trading tools for professional traders with AI-powered market intelligence

🎯 Status: Ready for Production

✅ All systems operational and optimized

• Fixed JSON serialization issues
• Optimized for minimal token usage (~50 tokens vs 60k+ previously)
• Robust error handling and caching
• Comprehensive tool suite with 50+ trading tools
• NEW: Market Intelligence System with 24/7 monitoring

📚 New User? Start with our Complete Windows Setup Guide - no experience required!

📁 Project Organization: See our Folder Organization Guide for the clean project structure.

---

This is the premium version of the Binance Futures MCP Server, providing comprehensive order management, risk management, advanced trading capabilities, and intelligent market analysis for professional algorithmic trading and portfolio management.

🧠 NEW: Market Intelligence System

Revolutionary Pre-Analyzed Market Data

Problem Solved: When AI assistants like GitHub Copilot analyze crypto markets, they typically make 400+ individual API calls for each token, causing massive delays and rate limiting.

Our Solution: 24/7 background monitoring with pre-calculated opportunity scores, delivering instant market analysis in seconds instead of minutes.

8-Factor Scoring System (0-60 points)

Our intelligent system analyzes every token using professional trading indicators:

1. 📈 Open Interest Changes (0-10 pts) - Detects position accumulation patterns
2. 💸 Volume Spikes (0-8 pts) - Identifies unusual trading activity
3. 🧨 Funding Rate Extremes (0-6 pts) - Spots squeeze opportunities
4. 🌀 Volatility Compression (0-5 pts) - Finds breakout candidates
5. 🐋 Whale Activity (0-6 pts) - Tracks institutional movements
6. 🗺️ Price Structure (0-4 pts) - Analyzes key support/resistance levels
7. 🧠 Sentiment/Narrative (0-4 pts) - Considers market themes (AI, L2, DeFi, etc.)
8. 📊 Volume/Market Cap Ratio (0-3 pts) - Measures relative activity

Market Intelligence Tools (9 new tools)

• get_market_opportunities - Get top-scored trading opportunities instantly
• get_token_analysis - Deep dive analysis for specific tokens
• get_market_dashboard - Comprehensive market overview
• get_funding_extremes - Find potential squeeze plays
• get_volume_leaders - Identify unusual volume activity
• get_volatility_squeeze - Discover breakout candidates
• get_whale_activity - Track institutional movements
• get_narrative_plays - Find tokens riding hot narratives
• get_quick_scan - Rapid high-conviction opportunities

Example Usage

Instead of waiting minutes for analysis, users can now ask:

"Analyze the crypto market and find the best long opportunities"

And get instant results like:

{
  "opportunities": [
    {
      "symbol": "SOLUSDT",
      "total_score": 52,
      "direction": "LONG", 
      "confidence": "HIGH",
      "recommendation": "STRONG LONG",
      "entry_timeframe": "IMMEDIATE",
      "score_breakdown": {
        "open_interest": 9,
        "volume_spike": 7,
        "funding_rate": 5,
        "volatility_squeeze": 4,
        "whale_activity": 6,
        "price_structure": 3,
        "sentiment": 4,
        "volume_mcap_ratio": 3
      }
    }
  ]
}

🚀 Premium Features

Order Management Tools (8 tools)

• place_order - Place market, limit, and conditional orders
• place_bracket_order - Advanced bracket orders with take-profit and stop-loss
• modify_order - Modify existing orders
• cancel_order - Cancel individual orders
• cancel_all_orders - Cancel all open orders for a symbol
• close_position - Close positions with market orders
• add_tp_sl_to_position - Add take-profit and stop-loss to existing positions
• get_order_status - Get detailed order status information

Risk Management Tools (4 tools)

• set_leverage - Adjust position leverage
• change_margin_type - Switch between cross and isolated margin
• modify_isolated_position_margin - Adjust margin for isolated positions
• get_position_margin_history - View margin adjustment history

Position Management Tools (3 tools)

• change_position_mode - Switch between hedge and one-way position modes
• get_position_risk - Get detailed position risk metrics
• get_adl_quantile - Get auto-deleveraging quantile information

Trading Configuration Tools (2 tools)

• set_multi_asset_mode - Configure multi-asset mode settings
• get_multi_asset_mode - Get current multi-asset mode status

Trading History Tools (4 tools)

• get_trade_history - Get account trade history
• get_order_history - Get historical order data
• get_income_history - Get income/PnL history
• get_commission_history - Get commission payment history

Enhanced Account Information (5 tools)

• get_account_info - Complete futures account information
• get_balance - Account balance details
• get_position_info - Current position information
• get_position_mode - Position mode settings
• get_commission_rate - Trading commission rates

Advanced Market Data (12+ tools)

• get_exchange_info - Exchange trading rules and symbol information
• get_ticker - Real-time price tickers
• get_order_book - Market depth data
• get_klines - Historical price data
• get_mark_price - Mark price and funding rates
• get_funding_rate_history - Historical funding rates
• get_top_gainers_losers - Market movers analysis
• get_market_overview - Comprehensive market statistics
• And more advanced market data tools...

🔐 Authentication & Security

The premium server requires member key authentication in addition to your Binance API credentials:

export BINANCE_API_KEY="your_api_key"
export BINANCE_SECRET_KEY="your_secret_key"
export BINANCE_MCP_MEMBER_KEY="your_premium_member_key"

Premium Member Key Validation

This package includes a premium member key validation system that authenticates premium users. The validation is handled automatically by the MCP server when you provide a valid member key. The system provides:

1. Secure key validation - Keys are validated against the premium database
2. Automatic authentication - No manual server configuration required
3. Seamless integration - Works directly with your MCP client configuration

� Project Structure

This project is now cleanly organized for better development experience:

premium_futures_mcp/
├── 📂 src/                    # Source code
├── 📂 docs/                   # All documentation
├── 📂 tests/                  # All test files
├── 📂 scripts/                # Utility scripts
├── 📂 docker/                 # Docker configuration
├── 📂 examples/               # Configuration examples
└── 📄 README.md              # This file

Key Benefits:

• 🧹 Clean root directory - No more scattered test files
• 📚 Organized documentation - All docs in docs/ folder
• 🧪 Centralized testing - All tests in tests/ folder
• 🐳 Docker isolation - Docker files properly separated
• 🔗 Easy access - Symlinks for frequently used files

See Folder Organization Guide for complete details.

�📦 Installation & Setup

✨ Simplified Setup: Version 1.0.1+ includes streamlined configuration that doesn't require separate VPS server setup for basic usage. Premium key validation is handled automatically.

From PyPI

pip install premium-futures-mcp==1.0.1

From Source

git clone <premium-repo-url>
cd premium_futures_mcp
pip install -e .

Configuration

Create an MCP configuration file (mcp-config.json):

Option 1: Direct Python Module (Recommended)

{
  "github.copilot.chat.mcp.servers": {
    "premium-binance-futures": {
      "command": "python3",
      "args": [
        "-m", 
        "premium_futures_mcp.server"
      ],
      "env": {
        "BINANCE_API_KEY": "your_api_key",
        "BINANCE_SECRET_KEY": "your_secret_key", 
        "BINANCE_MCP_MEMBER_KEY": "your_premium_member_key"
      }
    }
  }
}

Option 2: Using Docker Container

{
  "github.copilot.chat.mcp.servers": {
    "premium-binance-futures": {
      "command": "docker",
      "args": [
        "exec",
        "premium-mcp-server", 
        "python",
        "-m",
        "premium_futures_mcp.server"
      ]
    }
  }
}

Option 3: Using uvx (Alternative)

{
  "github.copilot.chat.mcp.servers": {
    "premium-binance-futures": {
      "command": "uvx",
      "args": [
        "--from", 
        "premium-futures-mcp==1.0.1", 
        "premium-futures-mcp-server"
      ],
      "env": {
        "BINANCE_API_KEY": "your_api_key",
        "BINANCE_SECRET_KEY": "your_secret_key", 
        "BINANCE_MCP_MEMBER_KEY": "your_premium_member_key"
      }
    }
  }
}

🐳 Docker Setup

For containerized deployment, see our Docker Setup Guide.

Quick Docker Start:

# Copy environment template
cp .env.example .env
# Edit .env with your API keys

# Start with docker-compose
docker-compose -f docker-compose.mcp.yml up -d

Note: Replace your_api_key, your_secret_key, and your_premium_member_key with your actual credentials. For security, consider using environment variables instead of hardcoding credentials.

🚨 Security Best Practices

1. Never commit API keys to version control
2. Use environment variables for all sensitive credentials
3. Restrict API permissions to futures trading only
4. Enable IP restrictions on your Binance API key
5. Monitor account activity regularly
6. Use isolated margin for risk management

🎯 Usage Examples

Basic Order Placement

# Place a market buy order
await client.call_tool("place_order", {
    "symbol": "BTCUSDT",
    "side": "BUY", 
    "type": "MARKET",
    "quantity": 0.001
})

# Place a limit sell order
await client.call_tool("place_order", {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "type": "LIMIT", 
    "quantity": 0.001,
    "price": 45000
})

Advanced Bracket Orders

# Place bracket order with TP/SL
await client.call_tool("place_bracket_order", {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "quantity": 0.001,
    "entry_type": "LIMIT",
    "entry_price": 42000,
    "take_profit_price": 45000,
    "stop_loss_price": 40000
})

Risk Management

# Set leverage for a symbol
await client.call_tool("set_leverage", {
    "symbol": "BTCUSDT",
    "leverage": 10
})

# Change margin type
await client.call_tool("change_margin_type", {
    "symbol": "BTCUSDT", 
    "margin_type": "ISOLATED"
})

📊 Monitoring & Analytics

The premium server includes advanced monitoring capabilities:

• Real-time position tracking
• PnL analysis and reporting
• Risk metrics calculation
• Performance analytics
• Commission tracking

🔧 Advanced Configuration

Premium Key Server Setup

The premium key server is responsible for validating member keys. Here's how to set it up:

Docker Deployment (Recommended)

# Start the key server with Docker
cd premium_futures_mcp
docker-compose up -d

# Check the server status
docker ps | grep premium-key-server

Systemd Deployment (Alternative)

# Install the service file
sudo cp premium_key_server.service /etc/systemd/system/
sudo systemctl daemon-reload

# Start and enable the service
sudo systemctl start premium_key_server
sudo systemctl enable premium_key_server

Key Generation

Generate premium member keys for your customers:

# Simple key generation
./create_customer_key.sh customer123 [e-mail]

# Advanced key generation with options
./generate_key.sh --id customer456 --email [e-mail] --days 90 --usage 100

Custom Risk Parameters

{
  "risk_management": {
    "max_position_size": 1000,
    "max_leverage": 20,
    "stop_loss_threshold": 0.05
  }
}

Performance Optimization

• Connection pooling for high-frequency trading
• Caching for market data
• Batch order processing
• WebSocket integration for real-time updates

📈 Professional Trading Features

Algorithmic Trading Support

• Advanced order types (OCO, conditional orders)
• Portfolio management tools
• Multi-symbol strategies
• Automated risk management

Institutional Features

• Sub-account management
• Advanced reporting
• Compliance tracking
• Audit trails

🆘 Support

For premium support and advanced features:

• Priority technical support
• Custom integration assistance
• Advanced strategy development
• Institutional-grade SLA

⚖️ License

Premium License - Commercial use requires valid subscription and member key authentication.

⚠️ Disclaimer

Trading futures involves substantial risk of loss. This software is provided for informational and educational purposes only. Always test strategies in a demo environment before live trading.

---

Total Tools: 50+ | Categories: 7 | Professional Grade ✨