How do I use mt4-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mt4-mcp show my current account balance" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mt4-mcp

by mergeos-bounties

Overview Schema Source Related Servers Discussions Admin

Python

Local

mt4-mcp

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

Related MCP server: OpenTrading

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

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing

ResponsivenessUnresponsive

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

openmm-mcp A
io.github.QBT-Labs
MCP server for OpenMM — exposes market data, account, trading, and strategy tools to AI agents
Finance
1513
Backtest360 A
com.backtest360
MCP server exposing the Backtest360 engine API as tools for AI agents.
Finance Research & Data
202
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
MTContext A
io.github.mtcontext
Connect any MCP client to MetaTrader 4/5 to read prices, manage positions, and place trades.
Finance Research & Data
1

Related MCP Servers

ctrader-mcp-server
Finance Research & Data
akinabudu
F
license
Not graded
quality
F
maintenance
A standalone Model Context Protocol (MCP) server that enables AI assistants to interact with the cTrader trading platform.
Updated a year ago (2025-10-10 23:29 UTC)
14
-
OpenTrading
Finance AI & Machine Learning Autonomous Agents
hyuwowo
A
license
Not graded
quality
D
maintenance
An open-source AI trading agent for MetaTrader 5 with MCP support, connecting AI clients to MT5 for market data, analysis, and risk-gated trading.
Updated 4 months ago (2026-05-07 15:09 UTC)
MIT
mt5-mcp
Finance Autonomous Agents
vincentwongso
A
license
A
quality
A
maintenance
An MCP server that lets an AI agent read your MetaTrader 5 account and place trades over the Model Context Protocol, with a configurable human approval gate.
Updated a month ago (2026-08-05 04:28 UTC)
15
5
MIT
mt5ctl
Finance Shell Access
Chust-dev
A
license
Not graded
quality
B
maintenance
An MCP server for operating headless MetaTrader 5 terminals — over SSH, from your agent.
Updated 2 months ago (2026-07-06 01:41 UTC)
MIT

mt4-mcp

Install (one command)

Grok — recommended

Other agents (stdio MCP)

Supported AI agents / hosts

Modes

Highlights

Quick start

CLI reference

MCP tools

Mock pending fills

MCP host config

Live bridge (optional)

Safety

Development

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

ctrader-mcp-server

OpenTrading

mt5-mcp

mt5ctl