MetaTrader 5 MCP Bridge

MetaTrader 5 MCP Bridge

让 AI Agent 通过 Model Context Protocol 管理你的 MetaTrader 5 账户，并可配置人工审批关卡。

_{Hermes Agent 在 demo 账户上完成一笔真实的 0.01 手交易，先开仓再平仓，全程通过 Linux 上的 MCP 操作。}

_{这不是模拟图——MetaTrader 5 自带的“历史”选项卡中显示了同一笔往返交易；订单号和余额都与录制内容一致。}

⚠️ 本软件会通过你的 MetaTrader 5 终端执行_真实_交易，产生真实订单和不可逆的成交。 阅读 DISCLAIMER.md 和 SECURITY.md 后，再将其连接到实盘账户。请务必先使用模拟账户进行测试。

在本地运行——与 Agent 位于同一进程树中，无云服务、无遥测。 支持 Windows（原生）或 Linux（通过 Docker）；Python 3.10+。

📖 项目背后的故事： 本项目是在 将 AI Agent 接入 MetaTrader 5 中逐步构建的；这是 Fintrix 工程博客《与 AI Agent 一起交易》系列的第 1 篇。

项目介绍

mt5-mcp 允许 AI Agent 读取你的 MetaTrader 5 账户信息，并通过 Model Context Protocol 执行交易。

• 12 个只读工具：账户、报价、持仓、订单、历史记录、OHLC K 线、由经纪商提供权威数据的保证金估算，以及原生图表截图 （Windows）。无需同意关卡。
• 4 个可变更数据的工具：place_order、modify_order、cancel_order、 close_position，每个工具都经过预检、人工同意、幂等和审计处理。
• 3 个可订阅资源：实时 account://、positions:// 和 quotes://{symbol} 快照，并推送变更通知。
• 附带 2 个可直接使用的 Claude Code 技能，位于 .claude/skills/： mt5-market-data 和 mt5-trading，用于指导 Agent 安全地读取账户信息并执行同意流程。

完整目录和同意流程：docs/tools.md。

为什么选择 mt5-mcp

• 安全层，而不只是 API 封装。 每次修改操作都会经过预检 -> 可选的人类同意关卡（启用后需获得批准）-> 幂等处理 -> 仅追加的审计日志，因此你可以让人类参与交易流程，并始终保留可重放的 Agent 操作记录。
• 坦诚的威胁模型。 它将连接到 place_order 的大模型视为实时攻击面，并直言不讳——MCP 明确不是安全边界（参见 SECURITY.md）。
• 可验证的证据，而非演示模型。 上方的演示是真实的往返操作；订单号和余额与 MetaTrader 5 自带的“历史”选项卡一致。
• 本地优先。 不使用云服务，也不收集遥测数据；与 Agent 在同一设备上运行。支持 Windows 原生运行，也可通过一体化 Docker 镜像在 Linux 上运行（无需匹配 rpyc 版本）。

快速开始（Windows，原生运行）

pip install mt5-trading-mcp

1. 启动 MetaTrader 5 并登录经纪商账户。启用 AlgoTrading（工具栏按钮变为绿色）。
2. 验证终端是否可访问：python -m mt5_mcp doctor：预期看到 [INFO] backend: native 和 [PASS] 行。
3. 运行：python -m mt5_mcp serve。

只需一条命令即可将其接入 OpenClaw（注册 mcp.servers 条目）：

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

快速开始（Linux，Docker）

MT5 终端和 MCP 在一体化镜像中以无头模式运行；你的 Agent 通过 HTTP 与 MCP 通信。无需在主机上安装 Python，也无需桥接程序。

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

通过 http://127.0.0.1:3001 上的 KasmVNC 网页界面登录终端一次（File -> Login to Trade Account；重启后仍会保留），然后让你的 Agent 连接 http://127.0.0.1:8765/mcp。只需一条命令即可将其接入 OpenClaw：

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

完整指南： docs/installation.md。

图表截图（仅限 Windows）

get_chart_screenshot(symbol, timeframe, annotations?) 会返回原生 MT5 图表的 PNG 图片，也可选择添加标注，让大模型以视觉方式读取图表（K 线、支撑位/阻力位、形态）。由于 MetaTrader5 Python API 无法截取图表，因此此功能使用一个在 GUI 终端内运行的轻量级 MQL5 EA，并调用 ChartScreenShot()。

如需在截图前标记支撑位/阻力位、趋势线和备注，请参阅图表标注。

一次性设置：

1. 安装并挂载 AgentScreenshot EA，参见 mql5/README.md。
2. 可选：设置模板，让指标和绘图内容显示在截图中：在配置文件中设置 [screenshot] template = "agent.tpl"，也可以留空以使用默认图表。

配置项（[screenshot] 区段）：width（默认值 1600）、height（默认值 900）、template（默认值 none）、timeout_s（默认值 10）。

无头 Linux/Docker 部署不支持此功能：它需要 GUI 终端。在 Windows 以外的平台上，此工具会返回 SCREENSHOT_NOT_SUPPORTED。

面向 AI Agent

如果你收到此代码库并要负责安装和运行，请按照 docs/agents.md 中的运行手册操作。 其中介绍了平台检测、安装、验证、注册服务以及交易的严格安全规则——调用任何修改类工具前，请先阅读。

文档

指南	内容
安装与设置	要求、Windows + Linux/Docker 设置，以及如何连接到 Agent。
面向 AI Agent	Agent 安装并运行服务的分步操作指南。
配置	config.toml 架构、存储路径、热重载。
工具与资源	读取工具、修改工具与同意流程、可订阅资源。
MCP 客户端设置	各客户端的配置片段和 Claude Code 用法。
传输与部署	stdio/HTTP 传输方式和 Windows VPS 部署模式。
贡献指南	如何贡献以及如何运行测试。
变更日志	发布历史和已知限制。

安全

mt5-mcp 不是安全边界；经纪商的 MT5 服务会强制执行硬性限制（保证金、最大手数、交易品种权限）。策略引擎中的预检是为了改善用户体验，帮助及早发现 Agent 的错误，而不是安全控制措施。

人工同意门默认关闭，需主动启用：auto_approve_notional 的默认值为 0，因此修改类调用会自动执行（完全开放）——适用于可信或无人值守的 Agent。将 auto_approve_notional 设为大于 0 即可启用同意门：名义金额达到或超过该值的订单/平仓操作会返回 ApprovalPreview，必须由你确认；扩大或移除止损的修改操作也需要审批。预检限制（max_*）和交易品种允许/拒绝列表同样需主动启用（0 / 空 = 关闭）。无论如何，每次修改类调用都会记录到只追加的审计 JSONL 日志中。有关漏洞披露，请参阅 SECURITY.md。

架构

mt5-mcp 通过 FastMCP 服务封装 MetaTrader 5 Python 库。单个 MT5Client（src/mt5_mcp/adapter/）负责终端连接、经纪商时区推断和类型转换；其他所有组件都构建在其之上。src/mt5_mcp/types.py / src/mt5_mcp/config.py 中的 Pydantic 模型是数据和配置架构的事实依据。

     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

所示的模块路径（tools/、resources/、policy/、streaming/、adapter/、types.py、config.py）都位于 src/mt5_mcp/ 下。

贡献

欢迎贡献，请参阅 CONTRIBUTING.md 了解开发环境设置、测试工作流和项目原则。

许可证

MIT - 详见 LICENSE。