MetaTrader MCP Server

---

📑 目录

• 这是什么？
• 功能
• 适用人群
• 重要免责声明
• 前置条件
• 快速开始
• 交易助手技能（Claude Code 和 Claude Desktop）
• 使用示例
• 可用操作
• WebSocket 报价服务
• 高级配置
• 路线图
• 开发
• 参与贡献
• 文档
• 获取帮助
• 许可证

---

🌟 这是什么？

MetaTrader MCP 服务是连接 AI 助手（如 Claude、ChatGPT）与 MetaTrader 5 交易平台的桥梁。你无需点击按钮，只需告诉 AI 助手你要做什么：

“查看我的账户余额” “买入 0.01 手 EUR/USD” “平掉所有盈利仓位”

AI 会理解你的请求，并自动在 MetaTrader 5 上执行。

工作原理

You → AI Assistant → MCP Server → MetaTrader 5 → Your Trades

✨ 功能

• 🗣️ 自然语言交易 - 用通俗易懂的语言与 AI 对话来执行交易
• 🤖 支持多种 AI - 兼容 Claude Desktop、ChatGPT（通过 Open WebUI）等
• 📊 全面访问市场 - 获取实时价格、历史数据和品种信息
• 💼 完整账户控制 - 查看余额、净值、保证金和交易统计数据
• ⚡ 订单管理 - 使用简单命令下单、修改和关闭订单
• 🔒 安全 - 所有凭据都保留在你的机器上
• 🌐 灵活的接口 - 可用作 MCP 服务、REST API 或 WebSocket 数据流
• 📖 文档完善 - 提供全面的指南和示例

🎯 适用人群

• 交易者：希望使用 AI 自动化交易
• 开发者：构建交易机器人或分析工具
• 分析师：需要快速访问市场数据
• 任何人：对结合 AI 与金融市场感兴趣

⚠️ 重要免责声明

请仔细阅读：

金融工具交易涉及重大亏损风险。本软件按“原样”提供，开发者对使用本软件导致的任何交易亏损、收益或后果概不负责。

使用本软件即表示你确认：

• 你了解金融交易的风险
• 你需对通过本系统执行的所有交易负责
• 你不会追究开发者对任何结果的责任
• 你使用本软件需自行承担风险

这不是金融建议。请始终负责任地交易。

---

📋 前置条件

开始之前，请确保你具备：

1. Python 3.10 或更高版本 - 在此下载
2. MetaTrader 5 终端 - 在此下载
3. MT5 交易账户 - 模拟账户或真实账户的凭据
   • 登录号码
   • 密码
   • 服务器名称（例如，“MetaQuotes-Demo”）

🚀 快速开始

第 1 步：安装软件包

打开终端或命令提示符并运行：

pip install metatrader-mcp-server

第 2 步：启用算法交易

1. 打开 MetaTrader 5
2. 转到 Tools → Options
3. 点击 Expert Advisors 选项卡
4. 勾选 Allow algorithmic trading
5. 点击 OK

第 3 步：选择接口

根据你的使用方式选择一种：

选项 A：与 Claude Desktop 配合使用（本地 STDIO）

1. 找到 Claude Desktop 配置文件：

   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Mac：~/Library/Application Support/Claude/claude_desktop_config.json

2. 打开文件并添加以下配置：

{
  "mcpServers": {
    "metatrader": {
      "command": "metatrader-mcp-server",
      "args": [
        "--login",     "YOUR_MT5_LOGIN",
        "--password",  "YOUR_MT5_PASSWORD",
        "--server",    "YOUR_MT5_SERVER",
        "--transport", "stdio"
      ]
    }
  }
}

可选：指定自定义 MT5 终端路径

如果 MT5 终端安装在非标准位置，请添加 --path 参数：

{
  "mcpServers": {
    "metatrader": {
      "command": "metatrader-mcp-server",
      "args": [
        "--login",     "YOUR_MT5_LOGIN",
        "--password",  "YOUR_MT5_PASSWORD",
        "--server",    "YOUR_MT5_SERVER",
        "--transport", "stdio",
        "--path",      "C:\\Program Files\\MetaTrader 5\\terminal64.exe"
      ]
    }
  }
}

3. 将 YOUR_MT5_LOGIN、YOUR_MT5_PASSWORD 和 YOUR_MT5_SERVER 替换为你的实际凭据

4. 重启 Claude Desktop

5. 开始聊天！试试提问：“我的账户余额是多少？”

选项 B：与 Open WebUI 配合使用（适用于 ChatGPT 和其他 LLM）

1. 启动 HTTP 服务：

metatrader-http-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER --host 0.0.0.0 --port 8000

可选：指定自定义 MT5 终端路径

如果 MT5 终端安装在非标准位置，请添加 --path 参数：

metatrader-http-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER --path "C:\Program Files\MetaTrader 5\terminal64.exe" --host 0.0.0.0 --port 8000

2. 在浏览器中打开 http://localhost:8000/docs，查看 API 文档

3. 在 Open WebUI 中：

   • 前往 设置 → 工具
   • 点击 添加工具服务
   • 输入 http://localhost:8000
   • 保存

4. 现在可以在 Open WebUI 聊天中使用交易工具了！

选项 C：通过 WebSocket 获取实时报价

通过 WebSocket 流式传输实时跳动数据（买价、卖价、点差、成交量），适用于仪表盘、机器人或监控：

metatrader-quote-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER

使用任意 WebSocket 客户端连接：

websocat ws://localhost:8765

你将收到一条 connected 消息，随后持续接收以 JSON 格式发送的跳动数据更新。详情请参阅 WebSocket 报价服务。

选项 D：远程 MCP 服务（SSE）

在 Windows VPS（已安装 MT5）上运行 MCP 服务，并从 Claude Desktop 或 Claude Code 远程连接。

服务端（在 Windows VPS 上）：

metatrader-mcp-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER

默认情况下，这会在 0.0.0.0:8080 上启动 SSE 服务。使用 --host 和 --port 自定义配置：

metatrader-mcp-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER --host 127.0.0.1 --port 9000

客户端（本地计算机上的 Claude Desktop 配置）：

{
  "mcpServers": {
    "metatrader": {
      "url": "http://VPS_IP:8080/sse"
    }
  }
}

将 VPS_IP 替换为服务端的 IP 地址。

安全警告：MCP 协议不包含身份验证。通过网络公开 SSE 服务时，请使用防火墙按 IP 限制访问，或将其置于带身份验证的反向代理之后，或使用 SSH 隧道。

---

🤖 交易助手技能（Claude Code / Claude Desktop）

claude-skill/ 目录中包含预构建的 交易终端助手 技能。它为 Claude 提供有关全部 32 个交易工具的结构化知识、输出格式规范以及 MetaTrader 5 领域专业知识。

为 Claude Code 安装

选项 1：创建符号链接（推荐）

从标准 Claude Code 技能目录创建指向 claude-skill/ 的符号链接：

cd metatrader-mcp-server
mkdir -p .claude
ln -s ../claude-skill .claude/skills

该技能会自动发现，并可通过 /trading 使用。

选项 2：复制

将技能文件复制到 Claude Code 技能目录：

cd metatrader-mcp-server
mkdir -p .claude/skills
cp -r claude-skill/trading .claude/skills/trading

为 Claude Desktop 安装

对于 Claude Desktop，将技能复制到全局 Claude 技能目录：

# macOS
mkdir -p ~/Library/Application\ Support/Claude/skills
cp -r claude-skill/trading ~/Library/Application\ Support/Claude/skills/trading

# Windows
mkdir "%APPDATA%\Claude\skills"
xcopy /E claude-skill\trading "%APPDATA%\Claude\skills\trading\"

技能功能

• 直接执行：请求交易时立即执行，无需额外确认
• 工作流：了解如何串联工具来完成复杂操作（例如，先下市价单，再设置 SL/TP）
• 格式化：将账户数据、持仓、订单和价格整理为清晰的终端风格表格
• 领域知识：理解 MT5 订单类型、时间周期、交易品种格式和成交模式

使用方法

安装后，使用 /trading 调用，或直接用自然语言提出交易相关问题：

/trading
> Show me my account dashboard
> Buy 0.1 lots of EURUSD with SL at 1.0800
> Close all profitable positions
> Show me GBPUSD H4 candles

---

📡 WebSocket 报价服务

WebSocket 报价服务将来自 MetaTrader 5 的实时跳动数据流式传输到任意 WebSocket 客户端。它适用于实时仪表盘、算法交易前端和实时监控。

启动服务

metatrader-quote-server --login YOUR_LOGIN --password YOUR_PASSWORD --server YOUR_SERVER

服务默认在 ws://0.0.0.0:8765 上启动。

自定义配置

metatrader-quote-server \
  --login YOUR_LOGIN \
  --password YOUR_PASSWORD \
  --server YOUR_SERVER \
  --host 127.0.0.1 \
  --port 9000 \
  --symbols "EURUSD,GBPUSD,XAUUSD" \
  --poll-interval 200

配置

标志	环境变量	默认值	说明
--host	QUOTE_HOST	0.0.0.0	绑定的主机
--port	QUOTE_PORT	8765	绑定的端口
--symbols	QUOTE_SYMBOLS	XAUUSD,USOIL,GBPUSD,USDJPY,EURUSD,BTCUSD	要推送的逗号分隔的交易品种
--poll-interval	QUOTE_POLL_INTERVAL_MS	100	行情轮询间隔，单位为毫秒

命令行标志优先于环境变量，环境变量优先于默认值。

消息格式

连接时——服务会发送包含交易品种列表的 connected 消息，随后发送所有已缓存的行情：

{"type": "connected", "symbols": ["XAUUSD", "EURUSD", "GBPUSD"], "poll_interval_ms": 100}

行情更新——每当买价、卖价或交易量发生变化时发送：

{"type": "tick", "symbol": "XAUUSD", "bid": 2345.67, "ask": 2345.89, "spread": 0.22, "volume": 1234, "time": "2026-03-14T10:30:45+00:00"}

错误——无法获取某个交易品种时发送：

{"type": "error", "symbol": "INVALID", "message": "Symbol not found or data unavailable"}

示例：使用 Python 连接

import asyncio
import json
from websockets.asyncio.client import connect

async def main():
    async with connect("ws://localhost:8765") as ws:
        async for message in ws:
            tick = json.loads(message)
            if tick["type"] == "tick":
                print(f"{tick['symbol']}: {tick['bid']}/{tick['ask']} (spread: {tick['spread']})")

asyncio.run(main())

设计说明

• 变更检测：仅在买价、卖价或交易量实际发生变化时广播，从而减少不必要的流量。
• 后来加入的客户端：新客户端连接后会立即收到已缓存的行情，无需等待下一次变更。
• MT5 线程安全：所有 MT5 SDK 调用都通过单线程执行器串行处理，以避免并发访问问题。
• 多个客户端：任意数量的 WebSocket 客户端都可以同时连接。

---

💡 使用示例

使用 Claude Desktop

配置完成后，你可以直接用自然语言交流：

查看账户：

你：“显示我的账户信息”

Claude：返回余额、净值、保证金、杠杆等信息

获取市场数据：

你：“EUR/USD 当前价格是多少？”

Claude：显示买价、卖价和点差

下单交易：

你：“买入 0.01 手 GBP/USD，止损设为 1.2500，止盈设为 1.2700”

Claude：执行交易并确认

管理持仓：

你：“平掉所有亏损的持仓”

Claude：平掉持仓并报告结果

分析历史记录：

你：“显示我上周所有 EUR/USD 交易”

Claude：以表格形式返回交易历史

使用 HTTP API

# Get account info
curl http://localhost:8000/api/v1/account/info

# Get current price
curl "http://localhost:8000/api/v1/market/price?symbol_name=EURUSD"

# Place a market order
curl -X POST http://localhost:8000/api/v1/order/market \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "EURUSD",
    "volume": 0.01,
    "type": "BUY",
    "stop_loss": 1.0990,
    "take_profit": 1.1010
  }'

# Get all open positions
curl http://localhost:8000/api/v1/positions

# Close a specific position
curl -X DELETE http://localhost:8000/api/v1/positions/12345

作为 Python 库使用

from metatrader_client import MT5Client

# Connect to MT5
config = {
    "login": 12345678,
    "password": "your_password",
    "server": "MetaQuotes-Demo"
}
client = MT5Client(config)
client.connect()

# Get account statistics
stats = client.account.get_trade_statistics()
print(f"Balance: ${stats['balance']}")
print(f"Equity: ${stats['equity']}")

# Get current price
price = client.market.get_symbol_price("EURUSD")
print(f"EUR/USD Bid: {price['bid']}, Ask: {price['ask']}")

# Place a market order
result = client.order.place_market_order(
    type="BUY",
    symbol="EURUSD",
    volume=0.01,
    stop_loss=1.0990,
    take_profit=1.1010
)
print(result['message'])

# Close all positions
client.order.close_all_positions()

# Disconnect
client.disconnect()

---

📚 可用操作

账户管理

• get_account_info - 获取余额、净值、利润、保证金水平、杠杆和货币

市场数据

• get_symbols - 列出所有可用的交易品种
• get_symbol_price - 获取某个交易品种当前的买价/卖价
• get_candles_latest - 获取近期价格 K 线（OHLCV 数据）
• get_candles_by_date - 获取指定日期范围内的历史 K 线
• get_symbol_info - 获取交易品种的详细信息

订单执行

• place_market_order - 执行即时买入/卖出订单
• place_pending_order - 设置限价单/止损单以供未来执行
• modify_position - 更新止损或止盈
• modify_pending_order - 修改挂单参数

持仓管理

• get_all_positions - 查看所有未平仓持仓
• get_positions_by_symbol - 按交易品种筛选持仓
• get_positions_by_id - 获取指定持仓的详细信息
• close_position - 平掉指定持仓
• close_all_positions - 平掉所有未平仓持仓
• close_all_positions_by_symbol - 平掉某个交易品种的所有持仓
• close_all_profitable_positions - 仅平掉盈利交易
• close_all_losing_positions - 仅平掉亏损交易

挂单

• get_all_pending_orders - 列出所有挂单
• get_pending_orders_by_symbol - 按交易品种筛选挂单
• cancel_pending_order - 取消指定挂单
• cancel_all_pending_orders - 取消所有挂单
• cancel_pending_orders_by_symbol - 取消某个交易品种的挂单

交易历史

• get_deals - 获取已完成交易的历史记录
• get_orders - 获取历史订单记录

---

🔧 高级配置

使用环境变量

不要将凭据放在命令行中，而是创建一个 .env 文件：

LOGIN=12345678
PASSWORD=your_password
SERVER=MetaQuotes-Demo

# Optional: Specify custom MT5 terminal path (auto-detected if not provided)
# MT5_PATH=C:\Program Files\MetaTrader 5\terminal64.exe

然后不带参数启动服务：

metatrader-http-server

服务会自动从 .env 文件加载凭据。

MCP 传输配置

MCP 服务支持多种传输模式：

标志	环境变量	默认值	描述
--transport	MCP_TRANSPORT	sse	传输类型：sse、stdio、streamable-http
--host	MCP_HOST	0.0.0.0	要绑定的主机（仅限 SSE/HTTP）
--port	MCP_PORT	8080	要绑定的端口（仅限 SSE/HTTP）

命令行标志的优先级高于环境变量，环境变量的优先级高于默认值。

自定义端口和主机（HTTP API）

metatrader-http-server --host 127.0.0.1 --port 9000

连接参数

MT5 客户端支持其他配置选项：

config = {
    "login": 12345678,
    "password": "your_password",
    "server": "MetaQuotes-Demo",
    "path": None,               # Path to MT5 terminal executable (default: auto-detect)
    "timeout": 60000,           # Connection timeout in milliseconds (default: 60000)
    "portable": False,          # Use portable mode (default: False)
    "max_retries": 3,           # Maximum connection retry attempts (default: 3)
    "backoff_factor": 1.5,      # Delay multiplier between retries (default: 1.5)
    "cooldown_time": 2.0,       # Seconds to wait between connections (default: 2.0)
    "debug": True               # Enable debug logging (default: False)
}

配置选项：

• login（int，必需）：你的 MT5 账户登录编号
• password（str，必需）：你的 MT5 账户密码
• server（str，必需）：MT5 服务名称（例如，“MetaQuotes-Demo”）
• path（str，可选）：MT5 终端可执行文件的完整路径。如果未指定，客户端会自动搜索标准安装目录
• timeout（int，可选）：连接超时时间，单位为毫秒。默认值：60000（60 秒）
• portable（bool，可选）：为 MT5 终端启用便携模式。默认值：False
• max_retries（int，可选）：最大连接重试次数。默认值：3
• backoff_factor（float，可选）：重试延迟的指数退避系数。默认值：1.5
• cooldown_time（float，可选）：两次连接尝试之间的最短时间，单位为秒。默认值：2.0
• debug（bool，可选）：启用详细调试日志以便排查问题。默认值：False

---

🗺️ 路线图

功能	状态
MetaTrader 5 连接	✅ 已完成
Python 客户端库	✅ 已完成
MCP 服务	✅ 已完成
Claude Desktop 集成	✅ 已完成
HTTP/REST API 服务	✅ 已完成
Open WebUI 集成	✅ 已完成
OpenAPI 文档	✅ 已完成
PyPI 软件包	✅ 已发布
SSE 传输支持	✅ 已完成
Google ADK 集成	🚧 进行中
WebSocket 报价服务	✅ 已完成
Docker 容器	📋 计划中

---

🛠️ 开发

设置开发环境

# Clone the repository
git clone https://github.com/ariadng/metatrader-mcp-server.git
cd metatrader-mcp-server

# Install in development mode
pip install -e .

# Install development dependencies
pip install pytest python-dotenv

# Run tests
pytest tests/

项目结构

metatrader-mcp-server/
├── src/
│   ├── metatrader_client/      # Core MT5 client library
│   │   ├── account/            # Account operations
│   │   ├── connection/         # Connection management
│   │   ├── history/            # Historical data
│   │   ├── market/             # Market data
│   │   ├── order/              # Order execution
│   │   └── types/              # Type definitions
│   ├── metatrader_mcp/         # MCP server implementation
│   ├── metatrader_openapi/     # HTTP/REST API server
│   └── metatrader_quote/       # WebSocket quote streamer
├── tests/                      # Test suite
├── docs/                       # Documentation
└── pyproject.toml             # Project configuration

---

🤝 参与贡献

欢迎贡献！你可以通过以下方式提供帮助：

1. 报告错误 - 提交问题
2. 建议功能 - 在问题中分享你的想法
3. 提交拉取请求 - 修复错误或添加功能
4. 改进文档 - 帮助让文档更清晰
5. 分享示例 - 展示你如何使用它

贡献指南

• Fork 此仓库
• 创建功能分支（git checkout -b feature/amazing-feature）
• 进行更改
• 编写或更新测试
• 确保测试通过（pytest）
• 提交更改（git commit -m 'Add amazing feature'）
• 推送到分支（git push origin feature/amazing-feature）
• 打开拉取请求

---

📖 文档

• 开发者文档 - 详细的技术文档
• API 参考 - 完整的 API 文档
• 示例 - 代码示例和教程
• 路线图 - 功能开发时间线

---

🆘 获取帮助

• 问题：GitHub Issues
• 讨论：GitHub Discussions
• LinkedIn：与我联系

常见问题

“连接失败”

• 确保 MT5 终端正在运行
• 检查是否已启用算法交易
• 确认登录凭据正确

“找不到模块”

• 确保已安装软件包：pip install metatrader-mcp-server
• 检查 Python 版本是否为 3.10 或更高版本

“订单执行失败”

• 确认经纪商处存在该交易品种
• 检查市场是否开市
• 确保保证金充足

---

📝 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

---

🙏 致谢

• 使用 FastMCP 构建，以支持 MCP 协议
• 使用 MetaTrader5 Python 软件包
• 由 FastAPI 提供支持，用于 REST API

---

📊 项目统计

• 版本：0.5.1
• Python：3.10+
• 许可证：MIT
• 状态：积极开发中

---