ali-rajabpour/metatrader-mcp

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)
• Python 3.10+

🚀 Quick Start

Step 1: Install Dependencies

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

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:

   {
     "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

🗂️ 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:

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

# 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 - For market data access
• MCP SDK - 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!