内容
# mt5-mcp
[](https://www.python.org/downloads/)
[](pyproject.toml)
[](LICENSE)
[](https://modelcontextprotocol.io)
**mt5-mcp** 是一个 [MCP](https://modelcontextprotocol.io) 服务器，允许 AI 代理检查和交易 **MetaTrader 5** 终端的账户、符号、报价、订单/仓位、历史记录，并具有完整的 **离线模拟** 功能，用于 CI 和演示。
---
## 模式
| 模式 | 何时 | 行为 |
| --- | --- | --- |
| **模拟** （默认） | Windows / CI / 无终端 | 种子演示账户，FX/CFD 符号，订单，历史记录 |
| **实时** | 主机配置了桥接 | 可选的文件/HTTP 桥接（参见环境变量）；如果不可用，则失败关闭 |
---
## 亮点
| 功能 | 描述 |
| --- | --- |
| **离线演示** | `mt5-mcp demo` 练习医生，报价，市场订单，历史记录 |
| **MCP 标准输入/输出服务** | 作为 MCP 服务器插入 Cursor / Claude / Grok |
| **一次性调用** | `mt5-mcp call …` 无需完整的 MCP 主机 |
| **安全性** | 模拟永远不会与真正的经纪人交谈；实时需要明确的环境 |
---
## 快速入门
```powershell
cd mt5-mcp
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"
mt5-mcp 版本
mt5-mcp 演示
mt5-mcp 工具列表
pytest -q
```
模拟模式不需要 **任何** MetaTrader 安装。
---
## CLI 参考
| 命令 | 目的 |
| --- | --- |
| `mt5-mcp 版本` | 版本 + 模式 |
| `mt5-mcp 状态` | 模式，余额，权益，仓位，订单 |
| `mt5-mcp 演示` | 核心后端 API 的离线烟雾测试 |
| `mt5-mcp 医生` | 后端健康检查 |
| `mt5-mcp 服务` | MCP 服务器通过 **标准输入/输出** |
| `mt5-mcp 调用 …` | 一次性工具调用 |
| `mt5-mcp 工具列表` | 列出 MCP 工具 |
```powershell
mt5-mcp 服务
```
---
## MCP 工具
| 工具 | 目的 |
| --- | --- |
| `mt5_mode` | 获取/设置模拟\|实时 |
| `mt5_doctor` | 连接性 / 账户健康检查 |
| `mt5_seed_demo` | 重置模拟账户 |
| `mt5_account` | 余额，权益，杠杆，交易模式 |
| `mt5_symbols` | 符号列表 |
| `mt5_quote` | 买入/卖出 / 最新 |
| `mt5_positions` | **开放仓位** （已成交的市场订单） |
| `mt5_orders` | **挂单** （限价/止损，未成交） |
| `mt5_order_send` | 市场/挂单 |
| `mt5_position_close` | 按票据关闭仓位 |
| `mt5_history_deals` | 交易历史记录 |
| `mt5://account` （资源） | 账户 + 仓位快照 |
---
## MCP 主机配置
```json
{
"mcpServers": {
"mt5-mcp": {
"command": "python",
"args": ["-m", "mt5_mcp"],
"env": {
"MT5_MCP_MODE": "模拟"
}
}
}
}
```
另请参阅 `examples/cursor_mcp.json`。
---
## 实时桥接（可选）
设置环境变量（永远不要提交秘密）：
| 变量 | 含义 |
| --- | --- |
| `MT5_MCP_MODE` | `模拟` 或 `实时` |
| `MT5_MCP_MAGIC` | 实时订单的可选魔术数字 | `202401` |
| `MT5_MCP_MAX_VOLUME` | 最大订单量上限 | `10.0` |
| `MT5_MCP_SYMBOL_ALLOWLIST` | 以逗号分隔的允许交易符号列表 | `EURUSD,GBPUSD` |
| `MT5_MCP_BRIDGE_URL` | 可选的 HTTP 桥接基准 URL |
| `MT5_MCP_BRIDGE_FILE` | 可选的请求/响应 JSON 文件路径 |
如果没有可用的桥接，**实时** 模式会返回结构化错误；演示仍保持在 **模拟** 状态。
---
## 安全性
| 规则 | 详情 |
| --- | --- |
| **仅模拟环境** | 复制 `examples/env.mock.example` → `.env` 并保持 `MT5_MCP_MODE=模拟` |
| **Git 中不包含秘密** | 将 `.env` 添加到 `.gitignore` — 永远不要提交实时经纪人凭证 |
| **最大交易量** | 设置 `MT5_MCP_MAX_VOLUME` 以限制实时模式下的任何单个订单 |
| **符号允许列表** | 通过 `MT5_MCP_SYMBOL_ALLOWLIST` （逗号分隔）限制可交易符号 |
---
## 交易历史记录
#### 交易历史记录字段
| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `ticket` | int | 交易 ID |
| `time` | str | 时间戳 |
| `symbol` | str | 工具 |
| `type` | str | 交易类型（买入/卖出） |
| `volume` | float | 交易量 |
| `price` | float | 成交价格 |
| `commission` | float | 经纪人佣金（模拟） |
| `swap` | float |隔夜利息（模拟） |
| `profit` | float | 净损益（模拟） |
---
## 开发
```powershell
pip install -e ".[dev]"
ruff check src tests
pytest -q
mt5-mcp 演示
```
---
## 许可证
[MIT](LICENSE)
