内容
# MTX — MT5 交易执行器 (用于 Claude Code 的 MCP 服务器)
```
███╗ ███╗████████╗██╗ ██╗
████╗ ████║╚══██╔══╝╚██╗██╔╝
██╔████╔██║ ██║ ╚███╔╝
██║╚██╔╝██║ ██║ ██╔██╗
██║ ╚═╝ ██║ ██║ ██╔╝ ██╗
╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝
MT5 交易执行器 · 执行、管理和保护真实交易
╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴
```
[](LICENSE)
[](https://www.python.org/)
[](https://www.metatrader5.com/)
[](https://modelcontextprotocol.io/)
[](#running-on-linux--macos-via-wine)
**通过与 Claude 对话，执行、管理和保护真实的 MetaTrader 5 交易 — 一个 Model Context Protocol (MCP) 服务器，将自然语言转换为经经纪商验证的 `order_send` 调用，并配置风险控制措施，防止错误交易。**
**要求：** Python 3.9+ · MetaTrader 5 (Windows，或通过 Wine 运行于 Linux/macOS) · Claude Code
MTX 是 **[MBT](https://github.com/FXDavid-OffbeatForex/MBT)** 的**执行端兄弟**：
MBT 读取和回测，MTX 执行和管理。它们共同覆盖整个循环 —
在真实的经纪商数据上验证策略，然后让 Claude 在真实（或模拟）账户上执行，每次确认一个交易。
- **打开、修改和关闭仓位** — 市价订单，部分平仓，止损/获利更新。
- **放置和管理挂单** — `buy_limit`，`sell_limit`，`buy_stop`，`sell_stop`，
可选过期。
- **基于风险的仓位大小** — 告诉它一个风险百分比或金额和止损距离；
返回一个经纪商正确的手数。
- **资金管理控制** — 最大开放仓位，每日亏损限制，权益止损，
保证金水平保护 — 在代码中强制执行，而不是交给模型的判断。
- **默认确认** — 每个写入工具首先预览经纪商的 `order_check`，并且
只有在您确认后（或您明确选择无人工干预的 `auto` 模式）才会执行交易。
---
## MTX 绝不猜测 — 经纪商始终拥有最终决定权
#1 个 bug 来源于手写的 MT5 自动化代码，即代码重新计算或假设经纪商约束 —
错误的填充模式，未四舍五入的手数，止损位于冻结水平内。MTX 不会猜测任何这些：
- 每个价格和交易量都针对符号自身的 `digits`、`volume_step`、
`volume_min/max` 和填充模式位掩码进行标准化，每个调用都从 `symbol_info` 中读取最新数据。
- 每个订单在发送任何内容之前都经过经纪商自己的 `order_check` —
MTX 预览经纪商将执行的操作，而不是它认为经纪商将执行的操作。
- 风险控制失败**安全失败**：如果风险检查无法评估，则阻止新交易，
而不是静默允许通过。
---
## 工作原理
```
您，在 Claude Code 中 MTX（此服务器）
┌───────────────────────┐ ┌──────────────────────────────┐
│ "买入 0.5 手 EURUSD, │ 调用 │ 标准化价格/交易量 │
│ 止损 1.0950, 获利 1.1100" ├──────────┤ 选择填充模式 │
└───────────────────────┘ │ mm.check_guardrails_block_new │
│ order_check → 预览 │
│ │ │
│ confirm=true 或 mode: auto │
│ ▼ │
│ order_send → 您的 MT5 终端 │
└──────────────────────────────┘
```
在默认的 `confirm` 模式下，每个写入工具返回一个验证的预览 —
余额，权益，保证金影响和经纪商的 `order_check` 验证结果 — 并且只有
您再次调用并使用 `confirm=true` 时才会执行。 将 `execution.mode` 切换到 `auto`
在 `config.yaml` 中进行无人值守使用（cron 驱动的 `mm_check` 心跳或无人工干预的
Claude Desktop 会话），并且每个开放仍然通过风险控制措施。
---
## 安装
```bash
git clone https://github.com/FXDavid-OffbeatForex/MTX.git
cd MTX
pip install -r requirements.txt
cp config.example.yaml config.yaml
```
编辑 **config.yaml**:
```yaml
mt5_path: "C:/Path/To/Your/terminal64.exe" # 要交易的终端
# 大多数设置已经登录 MT5 — 在这种情况下，可以完全省略此部分。
login:
account: null
password: "${MTX_PASSWORD}" # 将机密存储在 .env 中，而不是 config.yaml 中
server: null
execution:
mode: confirm # confirm | auto
magic: 770077 # MTX 自己的订单标记
deviation: 20 # 最大滑点，以点为单位
mm:
enforce: false # false = mm_check 仅报告；true = 它还会关闭
max_open_positions: 5
max_daily_loss_pct: 5.0
min_margin_level_pct: 200.0
equity_stop_pct: 20.0
```
将服务器注册到 Claude Code：
```bash
claude mcp add MTX python "/abs/path/to/MTX/mcp_server.py"
```
**使用 Claude Desktop 代替 Claude Code？** 打开
**设置 → 开发者 → 编辑配置** （这会打开 `claude_desktop_config.json`）
并添加：
```json
{
"mcpServers": {
"mtx": {
"command": "python",
"args": ["/abs/path/to/MTX/mcp_server.py"]
}
}
}
```
重启 Claude Desktop 以加载它。
就是这样 — 在 Claude Code 会话中 `ping` 以确认终端可达。
---
## 资金管理控制
风险控制是确定性的、基于配置的代码 — 永远不会交给模型的判断：
| 配置键 | 功能 |
|---|---|
| `max_open_positions` | 达到上限后拒绝新开仓 |
| `max_daily_loss_pct` / `max_daily_loss_money` | 今日实现的 + 浮动亏损达到限额时停止新开仓 |
| `min_margin_level_pct` | 保护：当保证金水平过低时标记/平仓 |
| `equity_stop_pct` | 保护：如果权益低于余额过多，则平仓所有仓位 |
| `close_position_loss_pct` / `close_position_loss_money` | 保护：在仓位损失超过限额时平仓单个亏损仓位 |
开仓动作在每次发送前检查这些 **，在 `confirm` 和 `auto` 模式下都是如此。**
保护方（`mm_check`）默认报告违规行为；设置 `mm.enforce: true`
它还会执行关闭 — cron 心跳在此处打开以进行无人值守保护。
---
## 工具（MCP）
**读取 — 安全，不需要确认：**
| 工具 | 目的 |
|---|---|
| `ping` | 检查 MT5 是否正在运行且可达 |
| `get_config` | 活动终端、账户、执行模式、资金管理摘要（密码已屏蔽） |
| `get_account_info` | 余额、权益、保证金、保证金水平、杠杆 |
| `get_symbol_info` | 位数、交易量步长、止损水平、填充模式、实时买卖价 |
| `get_positions` | 开仓仓位，可选按符号 |
| `get_pending_orders` | 有效挂单，可选按符号 |
| `get_history` | 关闭交易记录，指定日期范围 |
| `calc_position_size` | 根据风险 %/金额和止损距离计算仓位大小 |
| `mm_check` | 评估风险控制；如果 `mm.enforce: true` 也会执行 |
**写入 — 由 `confirm` / `execution.mode` 控制：**
| 工具 | 目的 |
|---|---|
| `open_position` | 开仓市场仓位（买入/卖出） |
| `place_pending_order` | 放置 `buy_limit` / `sell_limit` / `buy_stop` / `sell_stop` |
| `modify_position` | 改变开仓仓位的止损/获利 |
| `modify_pending_order` | 改变挂单的价格/止损/获利/到期时间 |
| `close_position` | 关闭仓位，全部或部分 |
| `cancel_pending_order` | 取消有效的挂单 |
---
## 示例
```
"我的账户余额和保证金水平是多少？"
"显示 EURUSD 当前的点差和最小止损距离。"
"以 200 点止损计算 GBPUSD 的 1% 权益风险仓位大小。"
"买入 0.1 手 XAUUSD，止损在 2340，目标在 2380。"
"将票号 65879650 的止损移动至盈亏平衡点。"
"在 USDJPY 上放置一个卖出限价，价格为 158.50，有效期至 2026-08-01。"
"检查我的风险控制 — 我距离今日亏损限额有多近？"
"关闭我一半的 EURUSD 仓位。"
```
上述每个交易示例在默认的 `confirm` 模式下都返回一个预览 —
Claude 向您显示经纪商自己的验证结果，然后再执行任何操作。
---
## 在 Linux / macOS 上运行（通过 Wine）
MetaTrader 5 及其 Python 包仅限 Windows，但 MTX 通过 [Wine](https://www.winehq.org/) 在 Linux 和
macOS 上运行良好 — 与 MBT 相同的方法：
1. 在 Wine 下安装 MT5（来自您的经纪商或 MetaQuotes）。
2. 在同一个 Wine 前缀中安装 Windows Python **并添加 MTX 的依赖项**：
```bash
wine /path/to/wine/python.exe -m pip install MetaTrader5 PyYAML mcp
```
3. 在 `config.yaml` 中指向 Wine 映射的终端路径，并在 Wine 启动器中注册服务器：
```json
{ "mcpServers": { "MTX": { "command": "wine", "args": ["/path/to/wine-python.exe", "/abs/path/to/MTX/mcp_server.py"] } } }
```
`MetaTrader5` Python 包通过 Windows DLL 与终端通信，因此它
必须在与终端相同的 Wine 前缀的 Python 中运行 — 而不是您的系统 Python。
---
## 超出范围（目前）
OCO/支架订单，服务器端跟踪止损，套期保值 `close_by`，部分填充
自动重试和多账户路由尚未实施。上面的工具界面已经
足够稳定，可以在不破坏现有调用的情况下添加它们。
---
## 风险说明
MTX 将在 `config.yaml` 指向的任何账户上执行真实订单。**请先在模拟账户上测试。**
默认的 `confirm` 模式和 `core/mm.py` 中的风险控制措施
存在于此，以便在没有您明确批准或您配置的限制的情况下，不会发生任何交易或失控损失。
该软件按原样提供（参见 [LICENSE](LICENSE)），不保证；
交易带有真实的金融风险，过去的表现不能保证未来的结果。
---
## 相关
- [MBT — MT5 回测工具包](https://github.com/FXDavid-OffbeatForex/MBT) —
读取/回测的兄弟端，该项目为其执行。
## 在 YouTube 上构建
该工具包是在 [FX David](https://www.youtube.com/@fxdavid9392) 的 YouTube 上直播构建的 —
一个关于使用 Claude AI 构建、验证和交易 MT5 策略的系列节目。
