Metadata-Version: 2.4
Name: mt5-trading-mcp
Version: 1.3.1
Summary: MCP server for MetaTrader 5: let an AI agent read market data, watch trades, and place real trades - behind a consent/audit safety layer. Windows + Linux (Docker).
Project-URL: Homepage, https://github.com/vincentwongso/mt5-trading-mcp
Project-URL: Repository, https://github.com/vincentwongso/mt5-trading-mcp
Project-URL: Documentation, https://github.com/vincentwongso/mt5-trading-mcp/tree/main/docs
Project-URL: Issues, https://github.com/vincentwongso/mt5-trading-mcp/issues
Project-URL: Changelog, https://github.com/vincentwongso/mt5-trading-mcp/blob/main/CHANGELOG.md
Author-email: Vincent Wongso Saputro <vincent.wongso.saputro@gmail.com>
License: MIT License
        
        Copyright (c) 2026 mt5-mcp contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai-agent,cfd,fastmcp,forex,llm,mcp,metatrader,metatrader5,model-context-protocol,mt5,trading
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.12
Requires-Dist: metatrader5>=5.0.45; platform_system == 'Windows'
Requires-Dist: platformdirs>=4.0
Requires-Dist: pydantic>=2.6
Requires-Dist: python-ulid>=3.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: watchdog>=4.0
Provides-Extra: bridge
Requires-Dist: mt5linux; extra == 'bridge'
Provides-Extra: dev
Requires-Dist: freezegun>=1.4; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# mt5-mcp

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

[![PyPI version](https://img.shields.io/pypi/v/mt5-trading-mcp.svg)](https://pypi.org/project/mt5-trading-mcp/)
[![PyPI downloads](https://img.shields.io/pypi/dm/mt5-trading-mcp.svg)](https://pypi.org/project/mt5-trading-mcp/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://pypi.org/project/mt5-trading-mcp/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/vincentwongso/mt5-trading-mcp/blob/main/LICENSE)
[![Tests](https://img.shields.io/github/actions/workflow/status/vincentwongso/mt5-trading-mcp/test.yml?branch=main&label=tests)](https://github.com/vincentwongso/mt5-trading-mcp/actions/workflows/test.yml)
[![GitHub stars](https://img.shields.io/github/stars/vincentwongso/mt5-trading-mcp?style=flat&label=stars)](https://github.com/vincentwongso/mt5-trading-mcp/stargazers)

<p align="center">
  <img src="https://raw.githubusercontent.com/vincentwongso/mt5-trading-mcp/main/demo/mt5-mcp-demo.gif" width="600" alt="mt5-mcp demo: an AI agent places and closes a live trade over MCP"><br>
  <sub>A <a href="https://github.com/NousResearch">Hermes</a> agent placing then closing a real 0.01-lot trade on a <b>demo</b> account, end-to-end over MCP on Linux.</sub>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/vincentwongso/mt5-trading-mcp/main/demo/mt5-history.png" width="820" alt="The same round-trip in MetaTrader 5's History tab"><br>
  <sub>Not a mock-up - the same round-trip in MetaTrader 5's own History tab; the tickets and balance match the recording.</sub>
</p>

> ⚠️ **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+.

## 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`.

## 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`. 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).
