# 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

## Setup

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

```bash
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:
```cmd
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:

```bash
claude mcp add mt4-server npm run start
```

Or configure manually with custom IP:

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

Or in your MCP settings:

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

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

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

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