MCP MetaTrader 4 Server

A Model Context Protocol (MCP) server that provides cross-platform integration with MetaTrader 4 trading platform over network.

Author: 8nite (8nite@qmlab.io)

Features

• Account Information: Get real-time account details (balance, equity, margin, etc.)
• Market Data: Retrieve current market prices for trading symbols
• Order Management: Place market and pending orders
• Position Management: View and close open positions
• Trading History: Access historical trading data
• Backtesting: Run backtests on Expert Advisors with detailed configuration
• Expert Advisor Management: List and manage available EAs
• File-Based Fallback: Robust status and results tracking when API endpoints fail
• EA Development: Remote EA creation, editing, sync, and compilation with error reporting
• Cross-Platform: Linux MCP server connects to Windows MT4 via HTTP

Architecture

The integration uses HTTP communication between the MCP server and MT4:

1. MCP Server (Linux - Node.js/TypeScript) - Provides tools for Claude Code
2. HTTP Bridge (Windows - Node.js) - Converts HTTP requests to file I/O
3. MT4 Expert Advisor (Windows - MQL4) - Handles trading operations
4. Network Communication - JSON-based data exchange via HTTP API

EA Development Workflow

List Local EAs

Show me all EAs in the active development folder

Sync EA to MT4

Upload MyStrategy EA to MetaTrader for compilation

Compile EA

Compile MyStrategy EA and show any errors or warnings

Create New EA from Template

cd ea-strategies
./develop.sh new MyNewStrategy SimpleMA_Template.mq4
./develop.sh edit MyNewStrategy

File Structure

├── src/
│   └── index.ts                    # MCP server implementation
├── mcp/                            # MCP infrastructure files
│   └── MCP_Ultimate.mq4           # Ultimate unified MCP Bridge with all features
├── strategies/                     # User trading strategies (git ignored)
│   └── [User strategy EAs]        # Custom trading strategies for personal use
├── ea-strategies/                  # EA development workspace (git ignored)
│   ├── templates/                  # EA templates and examples
│   ├── active/                     # EAs under development
│   ├── compiled/                   # Successfully compiled EAs
│   ├── logs/                       # Compilation logs and error reports
│   ├── develop.sh                  # Development helper script
│   └── README.md                   # EA development guide
├── MT4_Files/                      # Legacy MCP files
│   ├── MCPBridge_Unified.mq4      # Unified MCP Bridge with enhanced reporting
│   └── MCPBridge.mq4              # Legacy MCP Bridge (basic functionality)
├── dist/                          # Compiled JavaScript
├── MCPBridge_Unified_Guide.md     # Complete setup guide for unified EA
├── bridge-endpoints-needed.md     # Required HTTP bridge endpoints
├── package.json
└── tsconfig.json

Data Files

The Expert Advisor creates these files in MT4's MQL4/Files/ folder:

• account_info.txt - Account information
• market_data_[SYMBOL].txt - Market data for each symbol
• positions.txt - Open positions
• order_commands.txt - Incoming order commands
• close_commands.txt - Position close commands

File-Based Reporting (New Feature)

For enhanced backtest monitoring, EAs can write to the reports directory:

• mt4_reports/backtest_status.json - Real-time backtest status and progress
• mt4_reports/backtest_results.json - Detailed backtest results and statistics
• mt4_reports/backtest_report.html - Optional HTML report for detailed analysis

The MCP server automatically falls back to reading these files when API endpoints are unavailable.

Configuration: Set MT4_REPORTS_PATH environment variable to customize the reports directory (default: /tmp/mt4_reports)

Security Notes

• This integration is for educational/personal use
• Never share your MT4 login credentials
• Test thoroughly on a demo account before using with real money
• The file-based communication is simple but not encrypted

Environment Variables

• MT4_HOST: IP address of Windows machine running MT4 (default: 192.168.50.161)
• MT4_PORT: Port number for HTTP bridge (default: 8080)
• MT4_REPORTS_PATH: Directory path for EA report files (default: /tmp/mt4_reports)

EA Integration Guide

To enable file-based reporting in your Expert Advisors:

1. Copy the EA_FileReporting_Template.mq4 code into your EA
2. Call WriteBacktestStatus() periodically during backtesting
3. Call WriteBacktestResults() when backtest completes
4. Ensure MT4 has write permissions to the reports directory

The MCP server will automatically detect and use these files when API endpoints fail.

MCP Ultimate EA Features

MCP_Ultimate.mq4 is the most comprehensive MCP solution combining all functionality:

Key Features

• Complete MCP Bridge Functions: Account info, market data, order management
• Enhanced Backtest Reporting: Real-time status and comprehensive results with JSON format
• Visual Indicators: On-chart status display showing MCP connection and performance
• Advanced Market Data Tracking: Configurable tracking for major/minor/exotic pairs and commodities
• Comprehensive Logging: Detailed operation logs with automatic rotation
• Live Trading Support: Works seamlessly for both backtesting and live trading
• File-Based Fallback: Automatic fallback to file-based reporting when API endpoints fail
• Debug and Performance Monitoring: Real-time operation counters and performance metrics

Configuration Options

• MCP Bridge Settings: Update intervals, reporting toggles, visual mode
• Reporting Configuration: JSON format, detailed logs, maximum log files
• Market Data Settings: Selectable tracking for different currency pair types

Quick Setup

1. Use mcp/MCP_Ultimate.mq4 for complete functionality
2. Configure all options in EA inputs based on your needs
3. Full MCP functionality with enhanced visual feedback and monitoring

Organization Benefits

• MCP Infrastructure: All MCP-related files in mcp/ folder
• Strategy Separation: User strategies in strategies/ folder (git ignored)
• Development Workspace: EA development tools in ea-strategies/ (git ignored)
• Legacy Support: Previous versions maintained in MT4_Files/ for compatibility

See MCPBridge_Unified_Guide.md for detailed setup instructions on legacy versions.

Setup

1. Install MCP Server (Linux Machine - 192.168.50.X)

npm install
npm run build

2. Install HTTP Bridge (Windows Machine - 192.168.50.161)

1. Copy the windows-server/ folder to your Windows machine
2. Install Node.js on Windows if not already installed
3. Navigate to the windows-server folder and run:

npm install
npm start

4. The HTTP bridge will start on port 8080

3. Install MT4 Expert Advisor (Windows Machine)

Option A: Ultimate MCP EA (Recommended)

1. Copy mcp/MCP_Ultimate.mq4 to your MT4 MQL4/Experts/ folder
2. Compile the Expert Advisor in MetaEditor
3. Attach the Expert Advisor to any chart in MT4
4. Configure EA inputs:
   • EnableFileReporting: true (for enhanced reporting)
   • EnableBacktestTracking: true (for backtest monitoring)
   • EnableVisualMode: true (for on-chart status indicators)
   • Configure market data tracking options as needed
5. Ensure "Allow DLL imports" is enabled in MT4 settings

Option B: Unified EA (Legacy)

1. Copy MT4_Files/MCPBridge_Unified.mq4 to your MT4 MQL4/Experts/ folder
2. Follow same compilation and attachment process
3. Enhanced functionality but not as comprehensive as Ultimate version

Option C: Basic EA (Legacy)

1. Copy MT4_Files/MCPBridge.mq4 to your MT4 MQL4/Experts/ folder
2. Follow same compilation and attachment process
3. Limited to basic MCP functionality without enhanced reporting

4. Configure Claude Code (Linux Machine)

Add the MCP server to your Claude Code configuration:

claude mcp add mt4-server npm run start

Or configure manually with custom IP:

MT4_HOST=192.168.50.161 MT4_PORT=8080 claude mcp add mt4-server npm run start

Or in your MCP settings:

{
  "mcpServers": {
    "mt4-server": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "MT4_HOST": "192.168.50.161",
        "MT4_PORT": "8080"
      }
    }
  }
}

Usage

Once configured, you can use these tools in Claude Code:

Get Account Information

Use the get_account_info tool to see my MT4 account details

Get Market Data

Get current market data for EURUSD using get_market_data

Place Orders

Place a BUY order for 0.1 lots of EURUSD with stop loss at 1.0850 and take profit at 1.0950

View Positions

Show me all my open positions using get_positions

Close Position

Close position with ticket number 12345

Run Backtest

Run a backtest on MACD Sample Expert Advisor for EURUSD H1 from 2024-01-01 to 2024-12-31 with initial deposit 10000

List Expert Advisors

Show me all available Expert Advisors for backtesting

Get Backtest Results

Get the results from the last backtest with detailed information

Monitor Backtest Status

Check the current status of a running backtest

Limitations

• File I/O based communication has some latency
• Limited to MT4 platform capabilities
• Requires MT4 to be running with the Expert Advisor attached
• No real-time streaming data (periodic updates only)

Troubleshooting

1. MCP Server not responding: Check that MT4 is running with the Expert Advisor
2. No market data: Ensure the symbols are available in your MT4 Market Watch
3. Orders not executing: Verify that automated trading is enabled in MT4
4. File access errors: Check MT4 data path configuration and file permissions
5. Backtest status/results not available:
   • Check if API endpoints are responding (server will auto-fallback to files)
   • Ensure EA is writing to mt4_reports/ directory using the provided template
   • Verify MT4_REPORTS_PATH environment variable is set correctly
6. File-based fallback not working: Ensure reports directory exists and has proper permissions