Files

T

Devid HW e58316e70e feat: add check_update and update tools with background auto-check

On the first tool call of each session, a background task fires once
and fetches the latest release tag from the GitHub API (5 s timeout).
The result is cached in a static OnceLock for the lifetime of the
process — no repeated network calls.

check_update: returns cached result instantly, or fetches on demand
  if the background task hasn't completed yet.

update: downloads the latest tarball for the current platform, extracts
  the binary, and atomically replaces the running executable via a
  temp-file rename. Requires MCP reconnect to activate new version.

Platform support: macos-aarch64, macos-x86_64, linux-x86_64.
Unsupported platforms return a build-from-source hint.

Tool count: 87 → 89. README and MCP_TOOLS.md updated.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-22 07:34:25 +07:00

11 KiB

Raw Blame History

MT5-Quant

MCP server for MT5 strategy development on macOS/Linux. 87 tools to compile, backtest, analyze, optimize, debug crashes, and manage MQL5 Expert Advisors — no Windows required.

You: "Backtest MyEA Jan-Mar, what caused the February drawdown?"

Claude: [compile → clean → backtest → analyze 1,847 deals]
        → Feb 14: BUY grid at L6, locking lot 1.75× base
        → Cutloss fired 17 points later
        → Recommendation: cap locking multiplier to ≤1.2×

Why MT5-Quant

	MT5-Quant	Other MT5 MCPs	QuantConnect
Backtest pipeline	✅ Full	❌	Cloud only
Deal-level analytics	✅ 15+ dims	❌	❌
MQL5 compilation	✅	❌	❌
macOS/Linux native	✅	Windows only	Cloud
Optimization	✅ Background	❌	✅ Paid
Crash debugging	✅ Wine/MT5 diagnostics	❌	❌

Quick Install

1. Download & Setup

curl -L -o mt5.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mt5-quant-macos-arm64.tar.gz
tar -xzf mt5.tar.gz
bash scripts/setup.sh

2. Register MCP Server

Platform	Command / Config	Docs
Claude Code	`claude mcp add mt5-quant -- $(pwd)/mt5-quant`	Setup →
Windsurf	Edit `~/.codeium/windsurf/mcp_config.json`	WINDSURF.md →
Cursor	Edit `~/.cursor/mcp.json` or use Settings → MCP	CURSOR.md →
VS Code	Edit `.vscode/mcp.json` or run `MCP: Add Server`	VSCODE.md →
Claude Desktop	Agent Panel → ... → MCP Servers → Edit configuration	CLAUDE.md →

Note: Use absolute paths like /Users/name/mt5-quant/mt5-quant or $(pwd)/mt5-quant, not relative paths like ./mt5-quant.

Quick Start

Run a backtest on MyEA from 2025.01.01 to 2025.03.31

The AI runs the full pipeline: compile → clean cache → backtest → extract → analyze.

Documentation

Doc	Purpose
QUICKSTART.md	Complete setup for macOS/Linux
WINDSURF.md	Windsurf IDE setup
CURSOR.md	Cursor IDE setup
VSCODE.md	VS Code setup
CLAUDE.md	Claude Desktop setup
CONFIG.md	Configuration reference
TOOLS.md	All 87 tools documented
ARCHITECTURE.md	Design and internals
TROUBLESHOOTING.md	Common issues
REMOTE_AGENTS.md	Linux optimization agents

MCP Tools (89)

Core workflow

Tool	Description
`run_backtest`	Full pipeline: compile → clean → backtest → extract → analyze
`run_backtest_quick`	Quick backtest using pre-compiled EA (skip compile)
`run_backtest_only`	Backtest only - just extract raw trades, no analysis
`launch_backtest`	Fire-and-forget: launch MT5 backtest, poll for completion
`get_backtest_status`	Poll running backtest status (MT5 running, report found, elapsed time)
`run_optimization`	Genetic optimization (background, returns immediately)
`get_optimization_results`	Parse optimization results after MT5 finishes
`analyze_report`	Read `analysis.json` from any report directory
`compare_baseline`	Compare report vs baseline, return winner/loser verdict
`compile_ea`	Compile MQL5 EA via MetaEditor
`list_experts`	List all EAs in MQL5/Experts directory
`list_indicators`	List all indicators in MQL5/Indicators directory
`list_scripts`	List all scripts in MQL5/Scripts directory
`healthcheck`	Quick server health check

Granular Analytics (individual analysis)

Tool	Description
`analyze_monthly_pnl`	Monthly P/L breakdown only
`analyze_drawdown_events`	Drawdown events and causes only
`analyze_top_losses`	Worst losing deals only
`analyze_loss_sequences`	Consecutive loss patterns only
`analyze_position_pairs`	Position hold time and P/L pairs
`analyze_direction_bias`	Buy vs Sell performance
`analyze_streaks`	Win/loss streak analysis
`analyze_concurrent_peak`	Peak simultaneous positions

Use these for targeted analysis, or analyze_report to run all at once.

Deal-Level Analytics (New)

Tool	Description
`list_deals`	List individual deals with filters (type, profit range, volume, dates)
`search_deals_by_comment`	Full-text search in deal comments (e.g., "Layer #3")
`search_deals_by_magic`	Filter deals by EA magic number
`analyze_profit_distribution`	Profit histogram: small/medium/large wins and losses
`analyze_time_performance`	Performance by hour of day and day of week
`analyze_hold_time_distribution`	Hold time buckets + correlation with profit
`analyze_layer_performance`	Grid/martingale layer analysis from comments
`analyze_volume_vs_profit`	Volume correlation + performance by lot size
`analyze_costs`	Commission and swap impact on profitability
`analyze_efficiency`	Profit per hour/day, annualized return, trade frequency

Monitoring

Tool	Description
`verify_setup`	Check Wine/MT5 paths, Wine version, and EA/set file counts
`get_optimization_status`	Check live state of a background optimization job
`list_jobs`	All optimization jobs with compact status in one call

Reports & logs

Tool	Description
`list_reports`	Compact table of all runs with key metrics — no full analysis needed
`get_latest_report`	Get most recent report with optional equity chart
`search_reports`	Find reports by EA, symbol, date range, or profit criteria
`get_report_by_id`	Get specific report by ID with equity chart
`get_reports_summary`	Aggregate stats: counts, averages, pass rates
`get_best_reports`	Top N reports sorted by any metric (profit factor, drawdown, etc.)
`search_reports_by_tags`	Find reports by tags
`search_reports_by_date_range`	Query by backtest date range
`search_reports_by_notes`	Full-text search in report notes
`get_reports_by_set_file`	Find all reports using a specific .set file
`get_comparable_reports`	Find comparable reports (same EA/symbol/timeframe)
`tail_log`	Read last N lines of any log; `filter=errors` to see only failures
`prune_reports`	Delete old report directories, keep last N (skips `_opt` dirs)

History & baseline

Tool	Description
`archive_report`	Convert one report dir → compact JSON entry in `backtest_history.json`, optionally delete source
`archive_all_reports`	Bulk-archive all report dirs then optionally delete them; keeps N newest safe
`get_history`	Query history with filters (EA, symbol, verdict, profit, DD) and sort options
`annotate_history`	Attach verdict / notes / tags to any history entry
`promote_to_baseline`	Write a history entry or report to `baseline.json` for compare_baseline

Cache management

Tool	Description
`cache_status`	MT5 tester cache size breakdown by symbol — check before cleaning
`clean_cache`	Delete tester cache files; supports per-symbol and `dry_run`

Pre-flight & Validation

Tool	Description
`get_active_account`	Get current MT5 account session (login, server, available symbols)
`check_symbol_data_status`	Validate symbol has sufficient history data for date range
`check_mt5_status`	Check if MT5 terminal is installed and ready
`validate_ea_syntax`	Pre-compile syntax check without running full compilation

Debugging & Diagnostics (New)

Tool	Description
`diagnose_wine`	Check Wine installation, version, and prefix health
`get_mt5_logs`	Get MT5 terminal, tester, or MetaEditor logs with filtering
`search_mt5_errors`	Search logs for error patterns (crash, exception, access violation)
`check_mt5_process`	Check if MT5 processes are running, get PID, CPU, memory usage
`kill_mt5_process`	Kill stuck MT5 processes (force=true for wineserver)
`check_system_resources`	Check disk space, memory, CPU availability
`validate_mt5_config`	Validate terminal.ini and tester configuration files
`get_wine_prefix_info`	Get Wine prefix details: Windows version, installed programs, registry
`get_backtest_crash_info`	Investigate backtest failures: incomplete markers, missing deals.csv, errors

Project Management

Tool	Description
`init_project`	Scaffold new MQL5 project with templates (scalper/swing/grid/basic)
`create_set_template`	Generate .set parameter file from EA input variables
`export_report`	Export backtest report to CSV, JSON, or Markdown

History & Comparison

Tool	Description
`get_backtest_history`	List all backtests for EA/symbol with summary metrics
`compare_backtests`	Compare 2+ backtest results side-by-side with analysis

.set file — read / write

Tool	Description
`list_set_files`	All .set files in tester profiles dir with sweep stats and combination counts
`read_set_file`	Parse UTF-16LE `.set` file → structured JSON params
`write_set_file`	Write full params dict → UTF-16LE `.set` with `chmod 444`
`patch_set_file`	Update specific params in-place, return diff — replaces read→edit→write
`clone_set_file`	Copy `.set` to new path with optional overrides in one call

.set file — analysis & generation

Tool	Description
`describe_sweep`	Swept params, value counts, and total optimization combinations
`diff_set_files`	Side-by-side diff of two `.set` files — only changed params returned
`set_from_optimization`	Generate a clean backtest `.set` from `get_optimization_results` params; optionally narrow sweep

Search & Discovery

Tool	Description
`search_experts`	Search EAs by name pattern across all directories
`search_indicators`	Search indicators by name pattern
`search_scripts`	Search scripts by name pattern
`copy_indicator_to_project`	Copy indicator to project directory
`copy_script_to_project`	Copy script to project directory

Full schema: docs/MCP_TOOLS.md

Troubleshooting

Run verify_setup from Claude first — it checks all paths and returns actionable hints.

For crashes or unexplained failures during backtest/compile/optimization:

diagnose_wine — Check Wine installation and prefix health
search_mt5_errors — Find crash causes in logs
check_mt5_process + kill_mt5_process — Detect and kill stuck processes
get_backtest_crash_info — Investigate failed backtest reports

Full Troubleshooting Guide →

License

MIT

11 KiB Raw Blame History Unescape Escape