mt4-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:

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

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

---

Modes

---

Highlights

---

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. For a copy-pasteable offline trading walkthrough, see docs/MOCK_TRADING_DEMO.md.

---

CLI reference

mt4-mcp serve

---

MCP tools

---

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):

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

---

Safety

---

Development

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

---

License

MIT