# MetaTrader 5 MCP Server

A lightweight Model Context Protocol (MCP) server for MetaTrader 5 that provides **real chart snapshots** directly from your MT5 terminal - no browser automation needed!

## 🌟 Features

- � **Real MT5 Screenshots**: Captures actual charts from your MetaTrader 5 terminal with ALL your custom indicators
- 💹 **Market Data**: Fetch current prices, spreads, and symbol information  
- 🚀 **Lightweight**: Expert Advisor + file-based communication (no Selenium, no browser)
- 🔧 **Easy Integration**: Works seamlessly with Claude Desktop
- 🎨 **What You See Is What You Get**: Captures charts exactly as they appear in MT5
- ⚡ **Fast**: Direct chart capture via MQL5's ChartScreenShot function
- � **Secure**: File-based communication, no network ports required

## 🏗️ Architecture

This system uses an innovative approach:
- **MQL5 Expert Advisor**: Runs inside MT5, captures real charts using `ChartScreenShot()`
- **File-Based Protocol**: Commands/responses via shared text files (UTF-16 LE encoding)
- **Python MCP Server**: Communicates with EA, serves charts to Claude Desktop
- **MetaTrader5 API**: For market data and symbol information

**Key Advantage**: Captures REAL MT5 charts with all your custom indicators, drawings, and settings - exactly as you see them!

## 📋 Prerequisites

- **Windows OS** (MetaTrader 5 requirement)
- **MetaTrader 5** installed ([download here](https://www.metatrader5.com/))
- **Python 3.10+**

---

## 🚀 Quick Start

### Step 1: Install Dependencies

```powershell
cd d:\Desktop\metatrader-mcp
pip install -e .
```

### Step 2: Install Expert Advisor

1. **Copy the EA**:
   - Open MT5 → `File` → `Open Data Folder`
   - Navigate to `MQL5\Experts\`
   - Copy `expert_advisor\MCPChartCapture.mq5` to this folder

2. **Compile the EA**:
   - In MT5, press `F4` to open MetaEditor
   - Open `MCPChartCapture.mq5`
   - Press `F7` to compile (should show "0 errors")

3. **Attach to a chart**:
   - Open any chart in MT5 (e.g., EURUSD H1)
   - In Navigator (`Ctrl+N`), expand `Expert Advisors`
   - Drag `MCPChartCapture` onto the chart
   - In the dialog, go to `Common` tab:
     - ✅ Allow automated trading
   - Click `OK`

4. **Enable AutoTrading**:
   - Click the `AutoTrading` button in MT5 toolbar (or press `Ctrl+E`)
   - You should see a 😊 on the chart

### Step 3: Test the Setup

```powershell
python test_ea_connection.py
```

Expected output:
```
✅ Connected to MT5 v5370
✅ EA Response: EA is running
✅ Screenshot saved: output\EURUSD_H1_20251101_024101.png
All tests passed! ✅
```

### Step 4: Configure Claude Desktop

1. **Locate config file**:
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

2. **Add MCP server**:
   ```json
   {
     "mcpServers": {
       "metatrader5": {
         "command": "python",
         "args": ["-m", "metatrader_mcp.server"],
         "cwd": "d:\\Desktop\\metatrader-mcp"
       }
     }
   }
   ```

3. **Restart Claude Desktop**

4. **Test it**! Ask Claude:
   ```
   Show me a screenshot of EURUSD H1 chart
   ```

---

## 🛠️ Available Tools

### 1. `capture_chart_screenshot`
Capture a real screenshot from MT5 terminal with all your indicators.

**Parameters**:
- `symbol` (string): Trading pair (e.g., "EURUSD", "XAUUSD", "BTCUSD")
- `timeframe` (string): Chart timeframe - M1, M5, M15, M30, H1, H4, D1, W1, MN1

**Returns**: Path to the captured screenshot (PNG, 1920x1080)

**Example**:
```
Capture a screenshot of XAUUSD 15-minute chart
```

### 2. `list_symbols`
Get available trading symbols from MT5.

**Parameters**:
- `group` (string, optional): Filter by group (e.g., "Forex", "Crypto")

**Returns**: List of symbols with descriptions

**Example**:
```
Show me all Forex symbols
```

### 3. `get_current_price`
Get real-time market data for a symbol.

**Parameters**:
- `symbol` (string): Trading pair

**Returns**: Current bid, ask, spread, time

**Example**:
```
What's the current price of EURUSD?
```

### 4. `get_timeframes`
List all supported timeframes.

**Returns**: Available timeframe codes

---

## 📊 Supported Timeframes

| Code | Description |
|------|-------------|
| M1   | 1 minute    |
| M5   | 5 minutes   |
| M15  | 15 minutes  |
| M30  | 30 minutes  |
| H1   | 1 hour      |
| H4   | 4 hours     |
| D1   | Daily       |
| W1   | Weekly      |
| MN1  | Monthly     |

---

## 🗂️ Project Structure

```
metatrader-mcp/
├── expert_advisor/
│   └── MCPChartCapture.mq5      # MQL5 Expert Advisor for chart capture
├── src/
│   └── metatrader_mcp/
│       ├── server.py             # Main MCP server
│       ├── mt5_handler.py        # MT5 connection & market data
│       └── chart_generator.py    # EA communication & screenshot handling
├── output/                       # Captured screenshots (auto-created)
├── test_ea_connection.py         # Test EA connectivity
├── pyproject.toml                # Python dependencies
└── README.md
```

---

## 🔧 Troubleshooting

### ❌ EA not responding / Timeout errors

**Solutions**:
1. Check the EA is attached to a chart (you should see 😊)
2. Enable AutoTrading in MT5 (`Ctrl+E`)
3. Check Experts log in MT5 for errors
4. Try removing and reattaching the EA

### ❌ "MT5 initialization failed"

**Solutions**:
1. Verify MT5 is installed: `C:\Program Files\MetaTrader 5\terminal64.exe`
2. Open MT5 at least once to initialize
3. If custom install path, set `MT5_PATH` environment variable

### ❌ Screenshot file not found

**Solutions**:
1. Ensure EA is running (check for 😊 on chart)
2. Check Experts log for errors
3. Verify AutoTrading is enabled
4. Try capturing a chart that's already open

### ❌ "Could not fetch data for symbol"

**Solutions**:
1. The symbol must exist in your MT5 (check Market Watch)
2. Symbol names are case-sensitive
3. Try with "EURUSD" first to test

### ❌ Encoding errors / Garbled text

**Solution**: This is fixed! The system uses UTF-16 LE encoding for EA communication.

---

## 💡 Usage Examples

### Capture Chart with Custom Indicators
```
Claude, capture a screenshot of my XAUUSD M15 chart
```
→ Returns actual MT5 chart with all your custom indicators!

### Get Multiple Charts
```
Show me charts for EURUSD H1, GBPUSD H4, and XAUUSD M15
```

### Check Current Prices
```
What are the current prices for EURUSD, GBPUSD, and USDJPY?
```

### Explore Symbols
```
List all available Gold symbols
```

---

## 🧪 Testing

Run the test suite:

```powershell
# Test EA connection
python test_ea_connection.py

# Test chart capture
python take_screenshot.py

# Test specific symbol
python capture_xauusd.py
```

---

## 📝 Configuration (Optional)

Create a `.env` file for custom settings:

```env
# Custom MT5 installation path
MT5_PATH=C:\Program Files\MetaTrader 5

# Custom output directory for screenshots
OUTPUT_DIR=./charts
```

---

## 🤝 Contributing

Contributions are welcome! Feel free to:
- Report bugs
- Suggest features
- Submit pull requests
- Improve documentation

## 📄 License

MIT License - see LICENSE file for details

## 🙏 Acknowledgments

- [MetaTrader 5 Python API](https://www.mql5.com/en/docs/python_metatrader5) - For market data access
- [MCP SDK](https://modelcontextprotocol.io/) - Model Context Protocol implementation
- MQL5 Community - For Expert Advisor development resources

## 📞 Support

Having issues? Here's how to get help:

1. **Run diagnostics**: `python test_ea_connection.py`
2. **Check MT5 Experts log**: Look for error messages in MT5
3. **Verify setup**: EA attached? AutoTrading enabled? 😊 visible?
4. **Open an issue**: Include error messages and system info

---

**Made with ❤️ for traders who want to integrate MT5 with Claude AI**

*No browser automation. No Selenium. Just pure, lightweight MT5 chart capture!*