gridbot-mcp/README.md

# 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`:

```json
{
  "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`:

```bash
# 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

```bash
# 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/