Mt4

Python 3.11+ Version License: MIT MCP

mt4-mcp is an MCP server so AI agents can inspect and trade against a MetaTrader 4 terminal — account, symbols, quotes, orders/positions, history — with a full offline mock for CI and demos.

---

Install (one command)

Grok — recommended

pip install "git+https://github.com/mergeos-bounties/mt4-mcp.git" && grok plugin install mergeos-bounties/mt4-mcp --trust

This installs the Python CLI (mt4-mcp) and the Grok plugin (skill + MCP server from .mcp.json).

Check:

mt4-mcp version
mt4-mcp doctor
mt4-mcp demo
grok plugin list
grok mcp list

Local clone:

git clone https://github.com/mergeos-bounties/mt4-mcp.git
cd mt4-mcp
pip install -e ".[dev]"
grok plugin install . --trust

Other agents (stdio MCP)

After pip install "git+https://github.com/mergeos-bounties/mt4-mcp.git", point any MCP host at:

Field	Value
command	mt4-mcp
args	["serve"]
env	MT4_MCP_MODE=mock

Claude Desktop — merge examples/claude_desktop_config.json into Claude MCP config.

Cursor — merge examples/cursor_mcp.json.

Grok config.toml (manual, without plugin):

[mcp_servers.mt4_mcp]
command = "mt4-mcp"
args = ["serve"]
env = { MT4_MCP_MODE = "mock" }
enabled = true

One-liner via Grok CLI:

pip install "git+https://github.com/mergeos-bounties/mt4-mcp.git"
grok mcp add mt4-mcp -- mt4-mcp serve

Supported AI agents / hosts

Host	Support	Install
Grok (CLI / TUI / Build)	Yes	grok plugin install mergeos-bounties/mt4-mcp --trust then pip install "git+https://github.com/mergeos-bounties/mt4-mcp.git"
Claude Desktop	Yes	Copy examples/claude_desktop_config.json into Claude MCP settings
Cursor	Yes	Merge examples/cursor_mcp.json into Cursor MCP config
Claude Code	Yes	stdio MCP: same command/args as Claude Desktop / Grok
VS Code (MCP / Continue / Cline)	Yes	Generic stdio server config pointing at mt4-mcp serve
Windsurf / Cascade	Yes	stdio MCP entry with mt4-mcp + serve
Codex CLI	Yes (stdio)	Register MCP server command mt4-mcp serve in Codex MCP settings
ChatGPT Desktop	Partial	Only if host supports custom MCP stdio servers
Gemini CLI	Partial	Only if MCP stdio plugins are enabled

All packages speak MCP over stdio (mt4-mcp serve). Default mode is mock (offline, no simulator/terminal/GIMP required).

---

Modes

Mode	When	Behavior
mock (default)	Windows / CI / no terminal	Seeded demo account, FX/CFD symbols, orders, history
live	Host has a bridge configured	Optional file/HTTP bridge (see env vars); fails closed if unavailable

---

Highlights

Capability	Description
Offline demo	mt4-mcp demo exercises doctor, quotes, market order, history
MCP stdio serve	Plug into Cursor / Claude / Grok as an MCP server
One-shot call	mt4-mcp call … without a full MCP host
Safety	Mock never talks to a real broker; live needs explicit env

---

Quick start

cd mt4-mcp
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"

mt4-mcp version
mt4-mcp status
mt4-mcp demo
mt4-mcp tools list
pytest -q

Mock mode needs no MetaTrader install.

---

CLI reference

Command	Purpose
mt4-mcp version	Version + mode
mt4-mcp status	Mode, balance, equity, and open order count
mt4-mcp demo	Offline smoke of core backend APIs
mt4-mcp doctor	Backend health
mt4-mcp serve	MCP server over stdio
mt4-mcp call …	One-shot tool call
mt4-mcp tools list	List MCP tools

mt4-mcp serve

---

MCP tools

Tool	Purpose
mt4_mode	Get/set mock|live
mt4_doctor	Connectivity / account health
mt4_seed_demo	Reset mock account
mt4_account	Balance, equity, margin
mt4_symbols	Symbol list
mt4_quote	Bid/ask for a symbol
mt4_ticks	Recent quote ticks for a symbol
mt4_orders	Open orders
mt4_order_send	Market/pending OrderSend-style
mt4_order_modify	SL/TP/price modify
mt4_order_close	Close by ticket
mt4_history	Closed order history

---

Mock pending fills

In mock mode, pending orders are converted to market orders when quotes cross their trigger price. The mock supports deterministic tests for buy_limit, sell_limit, buy_stop, and sell_stop crossing behavior.

---

MCP host config

{
  "mcpServers": {
    "mt4-mcp": {
      "command": "python",
      "args": ["-m", "mt4_mcp"],
      "env": {
        "MT4_MCP_MODE": "mock"
      }
    }
  }
}

Also see examples/cursor_mcp.json.

---

Live bridge (optional)

Set env (never commit secrets):

Variable	Meaning
MT4_MCP_MODE	mock or live
MT4_MCP_BRIDGE_URL	Optional HTTP bridge base URL
MT4_MCP_BRIDGE_FILE	Optional request/response JSON file path

Without a working bridge, live mode returns structured errors; demos stay on mock.

---

Safety

Rule	Detail
Mock-only env	Copy examples/env.mock.example → .env and keep MT4_MCP_MODE=mock
No secrets in git	Add .env to .gitignore — never commit live broker credentials
Max volume	Set MT4_MCP_MAX_VOLUME to cap any single order in live mode
Symbol allowlist	Restrict tradeable symbols via MT4_MCP_SYMBOL_ALLOWLIST (comma-sep)

---

Development

pip install -e ".[dev]"
ruff check src tests
pytest -q
mt4-mcp demo

---

License

MIT