ztrade-mcp

ztrade 量化交易框架的 MCP (Model Context Protocol) Server 实现，使 AI 助手能通过标准化协议调用 ztrade 的核心功能。

功能特性

• MCP Tools — K线数据管理、策略回测、实盘交易、策略管理、任务管理、Python 研究执行
• 2 个 Resources — 策略开发文档、Engine API 参考
• 2 个 Prompts — 策略开发引导、回测分析引导
• 双传输模式 — stdio（本地 IDE）+ Streamable HTTP（远程 / Docker）
• 认证控制 — Bearer Token / API Key 两种模式，RBAC 角色权限
• Docker 支持 — 多阶段构建，一键部署

快速开始

编译

go build -o ztrade-mcp .

stdio 模式（本地 IDE）

./ztrade-mcp --config /path/to/ztrade.yaml

HTTP 模式（远程访问）

./ztrade-mcp --config /path/to/ztrade.yaml --transport http --listen :8080

命令行参数

配置文件自动搜索路径：$HOME/.configs/ztrade.yaml、./configs/ztrade.yaml、可执行文件同级 configs/ztrade.yaml。

MCP Tools

list_data — 查询本地数据

列出本地数据库中已有的 K 线数据集。

query_kline — 查询 K 线

从本地数据库查询 OHLCV 数据，供 AI 分析行情。

• 当请求周期大于 1m 时，会自动基于 1m 数据进行聚合（无需提前存储多周期表）。

run_python_research — Python 研究执行（DB 直读）

在独立的 python-runner 容器中执行 Python 代码，用于对行情进行研究/建模。

• Scheme B：python-runner 直接从数据库读取 K 线数据，避免将大量 OHLCV 通过 HTTP 传回 ztrade-mcp。
• MySQL 场景下 runner 强制使用只读账号（db.readonly.* 或 PYRUNNER_READONLY_*）。
• Runner 会提供 df（pandas.DataFrame，含 start/open/high/low/close/volume/turnover/trades 列，额外包含 time UTC 时间列）、以及 pd/np/load_kline。
• 镜像基于 Miniconda，内置常见量化库：numpy/pandas/scipy/statsmodels/scikit-learn/ta-lib/ta/empyrical/backtrader/plotly 等。
• 支持图像输出：可在代码中设置 images / image_path / image_paths / image_base64，或直接生成 matplotlib 图后不关闭，runner 会自动回传图片。

返回：文本 JSON（ok/error/stdout/stderr/result/meta）+ 可选 MCP 图片内容（images）。文本中仅包含图片元信息，图片本体通过 MCP image content 返回。

download_kline — 下载 K 线

从交易所下载历史 K 线数据到本地数据库。

run_backtest — 策略回测

使用策略脚本对历史数据进行回测，返回结构化结果。

返回指标：总收益率、年化收益率、夏普比率、索提诺比率、最大回撤、胜率、盈亏比、卡玛比率、综合得分等。

build_strategy — 编译策略

将 Go 策略源码编译为 plugin (.so)。

create_strategy — 生成策略骨架

根据模板生成策略代码骨架，包含标准的 ztrade 策略接口方法。

start_trade — 启动实盘

启动实盘交易实例。需要在配置中设置 mcp.enableLiveTrade: true。

stop_trade — 停止实盘

trade_status — 交易状态

MCP Resources

MCP Prompts

认证配置

stdio 模式 — 无需认证

stdio 模式由本地 IDE 启动进程，天然隔离。

Bearer Token 模式

mcp:
  auth:
    enabled: true
    type: token
    tokens:
      - token: "sk-ztrade-xxxxxxxxxxxxxxxxxxxx"
        name: "admin"
        role: admin
      - token: "sk-ztrade-yyyyyyyyyyyyyyyyyyyy"
        name: "readonly-bot"
        role: reader

API Key 模式

mcp:
  auth:
    enabled: true
    type: apikey
    header: "X-API-Key"
    keys:
      - key: "ak-ztrade-xxxxxxxxxxxxxxxxxxxx"
        name: "bot-1"
        role: trader

RBAC 角色权限

• reader：只读操作 + 回测 + 策略生成，不能执行有副作用的操作
• trader：reader 的全部权限 + 数据下载、策略编译、交易管理
• admin：全部权限

配置文件

复用 ztrade 的 ztrade.yaml 配置文件，额外支持 db.readonly（MySQL 只读账号）与 pyrunner 配置：

# 数据库（MySQL 示例）
db:
  type: mysql
  uri: root:root_password@tcp(mysql:3306)/exchange?charset=utf8mb4&parseTime=True&loc=Local
  readonly:
    type: mysql
    uri: exchange_readonly:change_me_readonly_password@tcp(mysql:3306)/exchange?charset=utf8mb4&parseTime=True&loc=Local

# 交易所
exchanges:
  binance:
    type: binance_futures
    key: "your-api-key"
    secret: "your-api-secret"

# Python 研究执行（python-runner）
pyrunner:
  url: "http://python-runner:9000"
  token: ""              # 可选；如设置需与 PYRUNNER_TOKEN 一致
  clientTimeout: 90s         # ztrade-mcp 调用 runner 的 HTTP 超时

# MCP 专属配置
mcp:
  listen: ":8080"
  enableLiveTrade: false     # 实盘交易安全开关
  auth:
    enabled: false
    type: token              # token 或 apikey
    tokens: []
    keys: []

Docker 部署

构建镜像

docker build -t ztrade/ztrade-mcp:latest .

使用 docker-compose

docker compose up -d

默认配置：

• 监听 :8080，端点 /mcp
• 配置文件挂载到 /etc/ztrade/ztrade.yaml
• 数据持久化到 ztrade-data volume
• 策略目录挂载为只读
• 健康检查端点 /health

docker-compose.yml 说明

services:
  ztrade-mcp:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - ./configs/ztrade.yaml:/etc/ztrade/ztrade.yaml:ro
      - ztrade-data:/data/ztrade
      - ./strategies:/strategies:ro

  python-runner:
    build: ./python-runner
    expose:
      - "9000"
    volumes:
      - ./configs/ztrade.yaml:/etc/ztrade/ztrade.yaml:ro
      - ztrade-data:/data/ztrade
    environment:
      - PYRUNNER_ZTRADE_CONFIG=/etc/ztrade/ztrade.yaml
      - PYRUNNER_TOKEN=${PYRUNNER_TOKEN:-}
      - PYRUNNER_READONLY_TYPE=${PYRUNNER_READONLY_TYPE:-}
      - PYRUNNER_READONLY_URI=${PYRUNNER_READONLY_URI:-}
      - PYRUNNER_READONLY_HOST=${PYRUNNER_READONLY_HOST:-}
      - PYRUNNER_READONLY_PORT=${PYRUNNER_READONLY_PORT:-}
      - PYRUNNER_READONLY_DATABASE=${PYRUNNER_READONLY_DATABASE:-}
      - PYRUNNER_READONLY_USER=${PYRUNNER_READONLY_USER:-}
      - PYRUNNER_READONLY_PASSWORD=${PYRUNNER_READONLY_PASSWORD:-}

说明：Scheme B 下 python-runner 需要能访问与 ztrade 相同的 K 线数据库。

• sqlite：将同一个 DB 文件/volume 挂载到 python-runner（示例里复用了 ztrade-data:/data/ztrade）。
• mysql：确保 runner 容器能访问 mysql 网络地址（示例里使用 mysql service），并配置 db.readonly.*（或 PYRUNNER_READONLY_*）以只读账号查询。
• 首次初始化 MySQL 前，可在 .env 设置 MYSQL_READONLY_USER / MYSQL_READONLY_PASSWORD，init-readonly.sh 会按环境变量创建只读账号。

客户端配置

Claude Desktop — stdio

{
  "mcpServers": {
    "ztrade": {
      "command": "/path/to/ztrade-mcp",
      "args": ["--config", "/path/to/ztrade.yaml"]
    }
  }
}

VS Code — stdio

.vscode/mcp.json:

{
  "servers": {
    "ztrade": {
      "type": "stdio",
      "command": "/path/to/ztrade-mcp",
      "args": ["--config", "/path/to/ztrade.yaml"]
    }
  }
}

VS Code — 远程 HTTP

{
  "servers": {
    "ztrade-remote": {
      "type": "http",
      "url": "http://your-server:8080/mcp",
      "headers": {
        "Authorization": "Bearer sk-ztrade-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

使用场景

AI 辅助策略开发

用户: 帮我写一个基于 EMA 金叉死叉的策略，快线9慢线26
AI:   [create_strategy] → 生成策略骨架
      [ztrade://doc/strategy] → 参考文档完善逻辑
      [run_backtest] → 回测 BTCUSDT 2024年数据
      → 分析结果：年化收益 15%，最大回撤 8%，夏普比率 1.2

AI 辅助回测分析

用户: 回测我的 boll.so 策略
AI:   [list_data] → 确认数据充足
      [download_kline] → 补充缺失数据
      [run_backtest] → 执行回测
      → 分析结果并给出优化建议

AI 管理实盘交易

用户: 把 ema_short.so 跑在币安 ETHUSDT 上
AI:   [start_trade] → 启动实盘，返回 tradeId
      [trade_status] → 监控运行状态
用户: 停掉
AI:   [stop_trade] → 停止交易

项目结构

ztrade-mcp/
├── main.go                # 入口：配置加载、DB 初始化、MCP Server 启动
├── go.mod
├── auth/
│   ├── auth.go            # User 模型、Config、RBAC 权限表、Token/APIKey 认证
│   └── middleware.go       # HTTP 认证中间件、ContextFunc、Tool 权限中间件
├── tools/
│   ├── register.go        # 注册全部 Tool
│   ├── list.go            # list_data
│   ├── kline.go           # query_kline
│   ├── download.go        # download_kline
│   ├── backtest.go        # run_backtest
│   ├── build.go           # build_strategy
│   ├── strategy.go        # create_strategy
│   └── trade.go           # start_trade / stop_trade / trade_status
├── resources/
│   ├── register.go        # 注册全部 Resource
│   ├── strategy_doc.go    # ztrade://doc/strategy
│   └── engine_doc.go      # ztrade://doc/engine
├── prompts/
│   ├── register.go        # 注册全部 Prompt
│   ├── strategy.go        # create_strategy prompt
│   └── backtest.go        # analyze_backtest prompt
├── Dockerfile             # 多阶段构建
├── docker-compose.yml     # 一键部署
├── python-runner/        # Python research runner (separate container)
└── .dockerignore

依赖

License

MIT