Metadata-Version: 2.4
Name: mt5-trading-mcp
Version: 1.2.1
Summary: Model Context Protocol server wrapping the MetaTrader 5 Python library.
Project-URL: Repository, https://github.com/vincentwongso/mt5-trading-mcp
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
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
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

[![PyPI version](https://img.shields.io/pypi/v/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)](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)

Model Context Protocol server wrapping the MetaTrader 5 Python library: exposes
a logged-in MT5 terminal as a set of MCP tools an AI agent can call.

<!-- Demo GIF goes here — e.g. ![mt5-mcp demo](assets/demo.gif) -->

> ⚠️ **This software places _real_ trades through your MetaTrader 5 terminal with
> real orders and irreversible fills.** Read [DISCLAIMER.md](DISCLAIMER.md)
> and [SECURITY.md](SECURITY.md) before connecting it to a live account. Always test
> using your demo account first.

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. It runs locally, in the same
process tree as your agent, no cloud, no telemetry.

- **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.

Full catalogue and the consent flow: **[docs/tools.md](docs/tools.md)**.

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

**Linux** (the MT5 terminal runs in an all-in-one Docker image; the agent talks
MCP over HTTP) and **wiring to an agent** are in
**[docs/installation.md](docs/installation.md)**.

## For AI agents

**If you are an AI agent and have been handed this repository to install and
run, follow this procedure.**

1. **Detect the platform and pick a backend.** Windows runs the `MetaTrader5`
   library natively; Linux runs the terminal in an all-in-one Docker image (the
   agent talks MCP over HTTP). Full per-platform steps:
   **[docs/installation.md](docs/installation.md)**.
2. **Install from this checkout:**
   - **Windows:** `pip install .` (or `uv sync --extra dev`). Tell the human to
     launch MetaTrader 5, log into their broker, and enable **AlgoTrading**.
   - **Linux (recommended):** bring up the Docker image — creds in
     `deploy/.env`, then `docker compose -f deploy/docker-compose.yml up -d`
     (it uses the published image; add `--build` only for local `deploy/`
     changes). The server runs in the container and serves MCP over HTTP; the
     one-time VNC login + bridge alternative are in `docs/installation.md`.
3. **Verify before doing anything else:** Windows → `python -m mt5_mcp doctor`
   (expect the backend + `[PASS]` lines); Docker image → after the human's
   one-time VNC login, your first `ping` returns `ok: true`. Do **not** proceed
   if verification fails — report it to the human and stop.
4. **Register / run the server:** Docker image → it's already serving; register
   `http://127.0.0.1:8765/mcp`. Windows → `python -m mt5_mcp serve` (stdio) with
   a config under [`examples/clients/`](examples/clients/) (e.g.
   [`hermes.json`](examples/clients/hermes.json)) that scopes you to the
   read-only tools by default.
5. **Operate read-only unless explicitly asked to trade.** The read tools are
   safe to call freely.
6. **⚠️ Hard rule, if live account and using real money.** `place_order`, `modify_order`, and
   `close_position` execute **real, irreversible trades**. When one returns an
   `ApprovalPreview`, show it **verbatim** to the human and only retry with
   `approval_confirmed=true` after they explicitly approve **that specific
   order**. Never auto-confirm, never batch-approve, never trade on a demo
   assumption — confirm it's a demo account first.

Tool semantics and the full consent flow: **[docs/tools.md](docs/tools.md)**.
Under Claude Code, the skills in `.claude/skills/` teach these directly.

## Documentation

| Guide | What's in it |
|---|---|
| [Installation & setup](docs/installation.md) | Requirements, Windows + Linux/Docker setup, wiring to an agent. |
| [Configuration](docs/configuration.md) | `config.toml` schema, storage paths, hot-reload. |
| [Tools & resources](docs/tools.md) | Read tools, mutating tools + consent flow, subscribable resources. |
| [MCP client setup](docs/clients.md) | Per-client config snippets and Claude Code usage. |
| [Transports & deployment](docs/deployment.md) | stdio/HTTP transports and Windows VPS patterns. |
| [Contributing](CONTRIBUTING.md) | How to contribute and run the tests. |
| [Changelog](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.

Mutating actions above the configured `auto_approve_notional` (or that widen
stops) require explicit human approval via the `ApprovalPreview` flow. Every
mutating call is recorded in an append-only audit JSONL log. For vulnerability
disclosure, see [SECURITY.md](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. On top of it: the MCP tools
(`src/mt5_mcp/tools/`), subscribable resources (`src/mt5_mcp/resources/`), the
consent / idempotency / audit layer (`src/mt5_mcp/policy/`), and the
change-detection streaming subsystem (`src/mt5_mcp/streaming/`). The Pydantic
models in `src/mt5_mcp/types.py` and `src/mt5_mcp/config.py` are the source of
truth for the data and config schemas.

## Contributing

Contributions are welcome, see [CONTRIBUTING.md](CONTRIBUTING.md) for the dev
setup, test workflow, and project principles.

## License

MIT - see [`LICENSE`](LICENSE).
