内容
# mt4-mcp
[](https://www.python.org/downloads/)
[](pyproject.toml)
[](LICENSE)
[](https://modelcontextprotocol.io)
**mt4-mcp** 是一个 [MCP](https://modelcontextprotocol.io) 服务器，允许 AI 代理检查和交易 **MetaTrader 4** 终端 — 账户、符号、报价、订单/仓位、历史 — 具有完整的 **离线模拟** 功能，用于 CI 和演示。
---
## 模式
| 模式 | 何时 | 行为 |
| --- | --- | --- |
| **模拟**（默认） | Windows / CI / 无终端 | 种子演示账户，FX/CFD 符号，订单，历史 |
| **实时** | 主机配置了桥接 | 可选文件/HTTP 桥接（参见环境变量）；如果不可用，则失败关闭 |
---
## 亮点
| 功能 | 描述 |
| --- | --- |
| **离线演示** | `mt4-mcp demo` 演练医生，报价，市场订单，历史 |
| **MCP 标准输入/输出服务** | 作为 MCP 服务器插入 Cursor / Claude / Grok |
| **一次性调用** | `mt4-mcp call …` 无需完整的 MCP 主机 |
| **安全性** | 模拟模式从不与真实经纪人通信；实时模式需要明确的环境 |
---
## 快速入门
```powershell
cd mt4-mcp
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"
mt4-mcp version
mt4-mcp status
mt4-mcp demo
mt4-mcp tools list
pytest -q
```
模拟模式不需要 **任何** MetaTrader 安装。
---
## CLI 参考
| 命令 | 目的 |
| --- | --- |
| `mt4-mcp version` | 版本 + 模式 |
| `mt4-mcp status` | 模式，余额，权益，开仓数量 |
| `mt4-mcp demo` | 核心后端 API 的离线测试 |
| `mt4-mcp doctor` | 后端健康检查 |
| `mt4-mcp serve` | 通过 **标准输入/输出** 的 MCP 服务器 |
| `mt4-mcp call …` | 一次性工具调用 |
| `mt4-mcp tools list` | 列出 MCP 工具 |
```powershell
mt4-mcp serve
```
---
## MCP 工具
| 工具 | 目的 |
| --- | --- |
| `mt4_mode` | 获取/设置模拟|实时 |
| `mt4_doctor` | 连接性/账户健康检查 |
| `mt4_seed_demo` | 重置模拟账户 |
| `mt4_account` | 余额，权益，占用保证金 |
| `mt4_symbols` | 符号列表 |
| `mt4_quote` | 指定符号的买入/卖出价 |
| `mt4_ticks` | 指定符号的近期报价 ticks |
| `mt4_orders` | 开仓订单 |
| `mt4_order_send` | 市场/挂单 OrderSend 风格 |
| `mt4_order_modify` | SL/TP/价格修改 |
| `mt4_order_close` | 按票据关闭 |
| `mt4_history` | 平仓历史记录 |
---
## 模拟待处理填充
在模拟模式下，待处理订单在报价交叉时转换为市价订单。模拟支持 `buy_limit`、`sell_limit`、`buy_stop` 和 `sell_stop` 交叉行为的确定性测试。
---
## MCP 主机配置
```json
{
"mcpServers": {
"mt4-mcp": {
"command": "python",
"args": ["-m", "mt4_mcp"],
"env": {
"MT4_MCP_MODE": "mock"
}
}
}
}
```
另请参阅 `examples/cursor_mcp.json`。
---
## 实时桥接（可选）
设置环境变量（永远不要提交机密）：
| 变量 | 含义 |
| --- | --- |
| `MT4_MCP_MODE` | `mock` 或 `live` |
| `MT4_MCP_BRIDGE_URL` | 可选的 HTTP 桥接基准 URL |
| `MT4_MCP_BRIDGE_FILE` | 可选的请求/响应 JSON 文件路径 |
如果没有可用的桥接，**实时** 模式将返回结构化错误；演示保持在 **模拟** 状态。
---
## 安全性
| 规则 | 详情 |
| --- | --- |
| **仅模拟环境** | 复制 `examples/env.mock.example` → `.env` 并保持 `MT4_MCP_MODE=mock` |
| **Git 中不存储机密** | 将 `.env` 添加到 `.gitignore` — 永远不要提交实时经纪人凭证 |
| **最大交易量** | 设置 `MT4_MCP_MAX_VOLUME` 以限制实时模式下的任何单个订单 |
| **符号允许列表** | 通过 `MT4_MCP_SYMBOL_ALLOWLIST`（逗号分隔）限制可交易符号 |
---
## 开发
```powershell
pip install -e ".[dev]"
ruff check src tests
pytest -q
mt4-mcp demo
```
---
## License
[MIT](LICENSE)
