# Mt5 Trading Mcp

> MCP server wrapping the MetaTrader 5 Python library, read market data, watch your trades, and place trades from your AI agent, with a consent/audit policy layer.

- **Type:** MCP server
- **Install:** `agentstack add mcp-vincentwongso-mt5-trading-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vincentwongso](https://agentstack.voostack.com/s/vincentwongso)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vincentwongso](https://github.com/vincentwongso)
- **Source:** https://github.com/vincentwongso/mt5-trading-mcp
- **Website:** https://engineering.fintrixmarkets.com

## Install

```sh
agentstack add mcp-vincentwongso-mt5-trading-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MetaTrader 5 MCP Bridge

**Let an AI agent manage your MetaTrader 5 account over [Model Context Protocol](https://modelcontextprotocol.io) - with configurable human approval gate.**

[](https://pypi.org/project/mt5-trading-mcp/)
[](https://pepy.tech/project/mt5-trading-mcp)
[](https://pypi.org/project/mt5-trading-mcp/)
[](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/LICENSE)
[](https://github.com/vincentwongso/mt5-trading-mcp/actions/workflows/test.yml)
[](https://github.com/vincentwongso/mt5-trading-mcp/stargazers)
[](https://modelcontextprotocol.io)
[](https://github.com/astral-sh/ruff)

  
  A Hermes agent placing then closing a real 0.01-lot trade on a demo account, end-to-end over MCP on Linux.

  
  Not a mock-up - the same round-trip in MetaTrader 5's own History tab; the tickets and balance match the recording.

> ⚠️ **This software places _real_ trades through your MetaTrader 5 terminal with
> real orders and irreversible fills.** Read
> [DISCLAIMER.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/DISCLAIMER.md)
> and [SECURITY.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/SECURITY.md)
> before connecting it to a live account. Always test using your demo account first.

Runs locally - in the same process tree as your agent, no cloud, no telemetry.
Windows (native) or Linux (via Docker); Python 3.10+.

> 📖 **The story behind this:** this project is built step by step in
> [*Wiring AI agent into MetaTrader 5*](https://engineering.fintrixmarkets.com/posts/mt5-mcp-part-1/),
> Part 1 of the *Trade with AI agent* series on the Fintrix engineering blog.

## What it is

`mt5-mcp` lets an AI agent read your MetaTrader 5 account and place trades
through it, over the Model Context Protocol.

- **11 read-only tools**: account, quotes, positions, orders, history, OHLC
  bars, and broker-authoritative margin estimates. No consent gate.
- **4 mutating tools**: `place_order`, `modify_order`, `cancel_order`,
  `close_position`, each behind a preflight + human-consent + idempotency +
  audit layer.
- **3 subscribable resources**: live `account://`, `positions://`, and
  `quotes://{symbol}` snapshots that push change notifications.
- **2 ready-to-use Claude Code skills** ship in
  [`.claude/skills/`](https://github.com/vincentwongso/mt5-trading-mcp/tree/main/.claude/skills):
  `mt5-market-data` and `mt5-trading` teach an agent how to read the account and
  run the consent flow safely.

Full catalogue and the consent flow: **[docs/tools.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/tools.md)**.

## Why mt5-mcp

- **A safety layer, not just an API wrapper.** Every mutating call routes through
  preflight checks -> an opt-in human-consent gate (arm it to require approval) ->
  idempotency -> an append-only audit log, so you can put a human in the loop on
  trades and always keep a replayable record of what the agent did.
- **An honest threat model.** It treats an LLM wired to `place_order` as a live
  attack surface and says so plainly - the MCP is explicitly *not* the security
  boundary (see [SECURITY.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/SECURITY.md)).
- **Verifiable proof, not a mock-up.** The demo above is a real round-trip; the
  tickets and balance match MetaTrader 5's own History tab.
- **Local-first.** No cloud, no telemetry; runs beside your agent. Windows-native
  or Linux via an all-in-one Docker image (no `rpyc` version-matching).

## Quickstart (Windows, native)

```bash
pip install mt5-trading-mcp
```

1. Launch MetaTrader 5 and log into your broker. Enable **AlgoTrading** (toolbar
   button green).
2. Verify the terminal is reachable: `python -m mt5_mcp doctor`: expect
   `[INFO] backend: native` and `[PASS]` lines.
3. Run it: `python -m mt5_mcp serve`.

Wire it to OpenClaw in one command (registers the `mcp.servers` entry):

```bash
openclaw mcp set mt5-mcp '{"command":"python","args":["-m","mt5_mcp","serve"]}'
```

## Quickstart (Linux, Docker)

The MT5 terminal + the MCP run headless in an all-in-one image; your agent talks
MCP over HTTP. No host Python, no bridge.

```bash
cp deploy/.env.example deploy/.env   # add MT5_LOGIN / MT5_PASSWORD / MT5_SERVER
docker compose -f deploy/docker-compose.yml up -d
```

Log the terminal in once via the KasmVNC web UI at `http://127.0.0.1:3001`
(**File -> Login to Trade Account**; persists across restarts), then point your
agent at `http://127.0.0.1:8765/mcp`. Wire it to OpenClaw in one command:

```bash
openclaw mcp set mt5-mcp '{"url":"http://127.0.0.1:8765/mcp","transport":"streamable-http"}'
```

Full walkthrough:
**[docs/installation.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/installation.md)**.

## For AI agents

**If you've been handed this repository to install and run, follow the runbook
in [docs/agents.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/agents.md).**
It covers platform detection, install, verification, registering the server, and
the hard safety rules for trades - read it before calling any mutating tool.

## Documentation

| Guide | What's in it |
|---|---|
| [Installation & setup](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/installation.md) | Requirements, Windows + Linux/Docker setup, wiring to an agent. |
| [For AI agents](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/agents.md) | Step-by-step runbook for an agent installing and running the server. |
| [Configuration](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/configuration.md) | `config.toml` schema, storage paths, hot-reload. |
| [Tools & resources](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/tools.md) | Read tools, mutating tools + consent flow, subscribable resources. |
| [MCP client setup](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/clients.md) | Per-client config snippets and Claude Code usage. |
| [Transports & deployment](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/docs/deployment.md) | stdio/HTTP transports and Windows VPS patterns. |
| [Contributing](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/CONTRIBUTING.md) | How to contribute and run the tests. |
| [Changelog](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/CHANGELOG.md) | Release history and known limitations. |

## Safety

`mt5-mcp` is **not** the security boundary, the broker's MT5 server enforces
the hard limits (margin, max-lot, symbol permissions). Pre-flight checks in the
policy engine are UX guardrails to catch agent mistakes early, not security
controls.

The human-consent gate is **opt-in and off by default**: `auto_approve_notional`
defaults to `0`, so mutating calls auto-execute (full-open) - intended for trusted
or unattended agents. **Arm the gate by setting `auto_approve_notional` > 0**:
orders/closes whose notional is at or above it then return an `ApprovalPreview`
you must confirm, and modifying a stop to widen or remove it also requires
approval. The pre-flight limits (`max_*`) and symbol allow/deny lists are likewise
opt-in (`0` / empty = off). Every mutating call is recorded in an append-only audit
JSONL log regardless. For vulnerability disclosure, see
[SECURITY.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/SECURITY.md).

## Architecture

`mt5-mcp` wraps the MetaTrader 5 Python library behind a FastMCP server. A single `MT5Client` (`src/mt5_mcp/adapter/`) owns the terminal connection, broker-timezone inference, and type conversions; everything else sits on top of it. The Pydantic models in `src/mt5_mcp/types.py` / `src/mt5_mcp/config.py` are the source of truth for the data and config schemas.

```
     Agent / MCP client  (Hermes, OpenClaw, Claude Code, Claude Desktop, …)
                               │
                               │   stdio  ·  loopback HTTP
                               ▼
 ┌──────────────────────────────────────────────────────────┐
 │                      FastMCP server                      │
 │                                                          │
 │   tools/        resources/        policy/                │
 │   read +        subscribable      consent · idempotency  │
 │   mutating      account/quotes    · audit (JSONL)        │
 │                                                          │
 │   streaming/  - change-detection poller + dispatcher     │
 │   types.py · config.py - Pydantic schemas: source of     │
 │                          truth for data + config         │
 │                                                          │
 └──────────────────────────────────────────────────────────┘
                               │
                               ▼
 ┌──────────────────────────────────────────────────────────┐
 │                                                          │
 │   adapter/  MT5Client                                    │
 │   one terminal connection · broker-TZ inference ·        │
 │   type conversions · transparent reinit                  │
 │                                                          │
 └──────────────────────────────────────────────────────────┘
                               │
                               ▼
MetaTrader 5 Python library  ->  broker terminal  ->  broker server
```

The module paths shown (`tools/`, `resources/`, `policy/`, `streaming/`,
`adapter/`, `types.py`, `config.py`) all live under `src/mt5_mcp/`.

## Contributing

Contributions are welcome, see
[CONTRIBUTING.md](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/CONTRIBUTING.md)
for the dev setup, test workflow, and project principles.

## License

MIT - see [`LICENSE`](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vincentwongso](https://github.com/vincentwongso)
- **Source:** [vincentwongso/mt5-trading-mcp](https://github.com/vincentwongso/mt5-trading-mcp)
- **License:** MIT
- **Homepage:** https://engineering.fintrixmarkets.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-vincentwongso-mt5-trading-mcp
- Seller: https://agentstack.voostack.com/s/vincentwongso
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.