metatrader5-mcp

A local MCP (Model Context Protocol) server that connects Claude (or any MCP client) to a running MetaTrader 5 terminal.

Phase 1 scope only: read-only market/account data, basic performance analysis, and order planning (margin/profit calculations, order validation, plan assembly). No tool in this server sends, modifies, or cancels an order, and live trading is always blocked. This is a read/analysis/planning foundation, not a trading bot.

Naming

The two names below differ intentionally:

• Repository / project identity: metatrader5-mcp
• Installable package / command: mt5-mcp (the Python import package is

mt5_mcp, and pip install -e . also exposes an mt5-mcp console command)

Requirements

• Windows, with a running MetaTrader 5 terminal (the MetaTrader5 Python

package only works on Windows, next to the terminal). On other platforms the server still runs and lists its tools, but every tool that touches MT5 will raise a clear MT5NotAvailableError.

• Python 3.10+

New to this on Windows? Follow docs/QUICKSTART_WINDOWS.md for a step-by-step setup, first tool calls, and a smoke-test checklist.

Install

python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -e .

Configure

Copy .env.example to .env and adjust as needed. Nothing here is a secret that gets committed - .env is gitignored, and the server never logs your password.

cp .env.example .env

Key settings:

Run the server locally

python -m mt5_mcp.server

This starts the MCP server over stdio. Point any MCP client (Claude Desktop, Claude Code, the mcp Python client, etc.) at this command. Example Claude Desktop / Claude Code config:

{
  "mcpServers": {
    "metatrader5": {
      "command": "python",
      "args": ["-m", "mt5_mcp.server"],
      "cwd": "/path/to/metatrader5-mcp"
    }
  }
}

See examples/example_client.py for a minimal standalone client that lists tools and calls one tool per permission tier (read, analysis, and a planning-only call that is never sent). examples/claude_desktop_config.example.json and examples/claude_code_config.example.json show client wiring with the venv's python.exe and an absolute cwd. docs/EXAMPLES.md walks through usage by tool group.

Before pointing a client at the server, you can run the read-only readiness helper to confirm your environment (it never plans or sends orders):

python scripts/mt5_readiness_check.py

What's implemented

SAFE_READ (always allowed, logged, no approval needed): get_account_info, get_terminal_info, get_symbol_info, get_tick, get_rates, get_positions, get_orders, get_history_deals, read_log, read_strategy_report.

SAFE_ANALYSIS (pure computation over data you already read, no approval needed): summarize_positions, analyze_drawdown, analyze_trade_history, calculate_profit_risk_basic.

REQUIRES_APPROVAL (order planning - margin/profit math and MT5's own dry-run order_check; a human must approve every call, and the risk guard still requires a demo account with MT5_MCP_ENABLE_DEMO_TRADING=true): calculate_margin, calculate_profit, check_order, prepare_order_plan.

BLOCKED (not implemented at all - no tool by these names exists, and the router refuses them by name as a safety net): sending, modifying, or cancelling any order; live trading in general.

See docs/TOOLS.md for full parameter reference, docs/EXAMPLES.md for usage examples by tool group, docs/TROUBLESHOOTING.md for a symptom → cause → fix guide, docs/SECURITY_MODEL.md for the canonical safety model (how the approval gate and risk guard work, and what is intentionally excluded), and docs/ARCHITECTURE.md for the module layout and request flow. docs/SAFETY.md is a short summary that points to docs/SECURITY_MODEL.md. See docs/RELEASE_CHECKLIST.md for the maintainer checklist used before tagging a release.

Run the tests

pip install -e ".[dev]"
pytest

Tests run against a fake in-memory MT5 module (see tests/conftest.py), so they pass on any platform without a real terminal.

Known limitations (Phase 1)

• No order execution (order_send) - intentionally not implemented.
• No VPS/remote mode, no plugin system, no multi-strategy framework.
• get_rates only supports the "most recent N bars" mode

(copy_rates_from_pos), not arbitrary date ranges.

• read_strategy_report uses a generic HTML table parser (label/value cell

pairing); unusual report layouts may need raw row inspection.

• The file-based approval mode polls the filesystem; it is not push-based.
• No persistence/database - approvals and logs are plain files.