Gridbot MCP Server

Exposes eToroGridbot trading bot operations via Model Context Protocol. Provides monitoring, trading, and analysis tools for the automated trading system.

Requirements

• VPN connection to services network: vpn-connect
• Gridbot conductor running on services VM (http://services:8001)
• Python 3.10+ with uv for development

Configuration

Add to ~/.claude/settings.json under mcpServers:

{
  "gridbot": {
    "command": "/path/to/gridbot-mcp/.venv/bin/python",
    "args": ["-m", "src.server"],
    "cwd": "/path/to/gridbot-mcp",
    "env": {
      "GRIDBOT_API_URL": "http://services:8001"
    }
  }
}

Tools

Monitoring

• health - Check conductor health, queue size, capacity
• emergency_status - Emergency stop status, circuit breaker, drawdown limits
• market_hours - Market hours for all exchanges (NYSE, NASDAQ, CRYPTO, FOREX)
• positions - All portfolio positions with real-time P/L
• pending_orders - Pending limit orders with amounts, rates, TP/SL
• risk_score - Portfolio risk score and components
• dashboard - Full dashboard (positions, orders, analytics)
• session_start - Comprehensive session summary (replaces 5-6 individual calls)

Market Data

• vix - VIX volatility index and interpretation
• crypto_fear_greed - Crypto Fear & Greed index with trading guidance

Trading Operations

• validate_trade - Validate trade before execution (checks risk limits)
• create_order - Create BUY/SELL order with full validation
• close_position - Close existing position (full or partial)
• close_positions_by_filter - Close multiple positions (e.g., all crypto, all losers)
• cancel_order - Cancel single pending order
• cancel_orders_bulk - Cancel multiple orders at once
• find_duplicate_orders - Find duplicate pending orders
• emergency_stop - HALT all trading (emergency use only)
• emergency_reset - Resume trading after emergency stop
• cleanup_stale_orders - Cleanup stale/expired orders

Signal Intents (Limit Orders)

• intents - List signal intents (pending orders awaiting trigger)
• intents_pending - List pending intents only
• intents_executed - List executed intents
• intents_stats - Intent statistics (pending/executed/expired)
• create_intent - Create signal intent (limit order)
• create_intents_bulk - Create multiple intents at once
• cancel_intent - Cancel pending intent

Scale-Out (Profit Taking)

• scale_out_status - Scale-out monitor status
• scale_out_pending - Positions pending scale-out
• scale_out_stats - Scale-out statistics (P/L locked)
• scale_out_trigger - Manually trigger scale-out for position
• scale_out_adjust_threshold - Override threshold for symbol
• scale_out_get_overrides - Get all threshold overrides
• scale_out_delete_override - Delete threshold override
• scale_out_set_dry_run - Enable/disable dry-run mode

Analysis

• trades - Recent trades with P/L details
• analytics - Trading analytics (win rate, Sharpe ratio)
• expectancy - Trading expectancy metrics by symbol
• profitable_symbols - Profitable symbols ranked by expectancy
• correlations - Top correlated asset pairs
• signal_quality - Signal acceptance rate, rejection reasons
• trend_alerts - Active trend change alerts
• statistics - Trading statistics summary
• support_resistance - Support/resistance levels for symbol

System

• queue_status - Signal processing queue status
• bot_health - Trading bot health (Freqtrade, Hummingbot)
• stale_bots - Bots with no recent signals
• monitoring_stats - System monitoring stats
• env_health - Environment health (API keys, credentials)
• candle_freshness - Candle data staleness check
• rate_limiter - Rate limiter statistics
• portfolio_allocation - Portfolio allocation breakdown
• market_closure_context - Market closure context
• container_logs - Get container logs with grep filter
• container_restart - Restart a container
• pi_consensus_query - Get PI consensus data for symbol
• pi_consensus_top - Get top PI consensus opportunities
• pi_scan_trigger - Trigger manual PI portfolio scan

CLI Wrapper

A command-line wrapper is available at ~/Development/Infrastructure/AgilitonScripts/bin/gridbot:

# Session start (recommended)
gridbot session-start              # Comprehensive session summary

# Monitoring
gridbot health                     # Check system health
gridbot positions                  # List all positions
gridbot pending                    # Show pending orders
gridbot risk                       # Portfolio risk score
gridbot dashboard                  # Full dashboard

# Market data
gridbot market-hours               # Market hours
gridbot vix                        # Volatility index
gridbot crypto-fear-greed          # Fear & Greed index

# Trading validation
gridbot validate BTC BUY 100       # Validate $100 BTC buy

# Analysis
gridbot trades                     # Recent trades
gridbot analytics                  # Trading performance
gridbot expectancy                 # Expectancy by symbol
gridbot profitable                 # Best performing symbols
gridbot correlations               # Correlated pairs
gridbot statistics                 # Trading statistics

# System
gridbot queue                      # Queue status
gridbot bot-health                 # Bot health
gridbot monitoring                 # System stats
gridbot env-health                 # Environment check
gridbot candle-freshness           # Data freshness

# Emergency
gridbot emergency-stop "reason"    # HALT trading
gridbot emergency-reset            # Resume trading
gridbot cleanup-orders             # Cleanup stale orders

The CLI wrapper provides terminal access to all MCP tools without requiring Claude Code.

Development

# Setup
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

# Run
python -m src.server

Architecture

• Conductor API: Trading bot coordinator (services:8000)
• Position Management: Real-time P/L tracking with BotPriceProvider
• Risk Management: Portfolio risk scoring, circuit breakers
• Signal Intents: Limit orders with trigger price
• Scale-Out: Automated profit-taking at thresholds
• PI Consensus: Portfolio Intelligence integration
• Market Hours: Dynamic allocation based on market status

Related

• Conductor: /Users/christian.gick/Development/Apps/eToroGridbot
• Dashboard: http://services:5555
• Documentation: ClaudeFramework/docs/gridbot/