同花顺 Web Paper Trading MCP Service

把同花顺交易系统封装成通用 MCP 服务（stdio），供各类 AI Agent 调用。

实践案例：两个 MCP 配合，全自动炒股

• 本项目的 MCP 服务负责「账户持仓」「下单交易」

• 同花顺 iFinD AI 金融数据服务负责「查数据选股」「查行情指标」（同花顺有免费试用额度）。

两个服务同时接入同一个AI代理（如 hermes、codex、claude desktop、workbuddy、trae work 和 deepseek harness 等）后， 你只需告诉 AI「按 XX 策略自动炒股」，它就会自己用 iFinD 查行情选股，再用交易服务自动 下单、撤单、查成交，全程不用人工操作账户。

重要提醒

• 先启动浏览器并登录同花顺交易系统（见「使用前提」）。交易服务才能下单。

• **下单只支持市价：**数量必须为 100 的整数倍；买入前 AI 会先查资金，卖出前会先查持仓。

• AI 炒股，盈亏自负！ 不要滥用本工具，更不能用于商业用途。

• 本工具只能做模拟交易。如果交易策略验证后你想在真实账户上线怎么办？请联系作者，会有解决方案！

Related MCP server: TickTest MCP Server

使用前提

1. 人工启动浏览器（详见 启动浏览器.bat）：Chrome 开启 9222 调试端口，使用独立用户目录 chrome_profile。

2. 人工登录同花顺交易系统，并进入交易页面。

3. 满足以上条件后 MCP 服务才能正常工作；否则各工具会返回明确的中文错误提示。

环境

• 推荐 Python 版本：3.11（mcp 依赖要求 >=3.10，3.10–3.12 均可正常使用）

• Python 环境：项目内 .venv（虚拟环境，见下节创建方式）

• 依赖：.venv/Scripts/python.exe -m pip install -r requirements.txt

• 说明：Playwright 通过 CDP 连接已打开的浏览器，无需下载浏览器内核；也不存储任何账号凭证，完全依赖人工登录好的会话。

创建 Python 虚拟环境

首次使用需在项目根目录下创建 .venv（方法二选一）：

# 方式一：标准库 venv（需本机已安装 Python 3.11，可用 py -3.11 指定版本）
py -3.11 -m venv .venv

# 方式二：uv（更快，未装对应版本时自动下载，推荐）
uv venv --python 3.11 .venv

依赖创建完成后安装依赖：

.venv/Scripts/python.exe -m pip install -r requirements.txt

Windows 下解释器路径为 .venv/Scripts/python.exe（Linux/macOS 为 .venv/bin/python）。 后续所有命令均以 .venv/Scripts/python.exe 为准。

MCP 配置教程

本服务通过 stdio 传输运行，任何支持 MCP 的客户端都可接入。核心配置只有一行： 用项目 .venv 的 Python 解释器启动 server.py。

通用配置（适用于任意 AI Agent）

{
  "mcpServers": {
    "ths-stock-trading-mcp": {
      "command": "D:/workspace_github/ai_ths_moni_trading_mcp/.venv/Scripts/python.exe",
      "args": ["D:/workspace_github/ai_ths_moni_trading_mcp/server.py"]
    }
  }
}

Windows 路径可使用正斜杠 D:/...；如果你的 .venv 实际所在路径不同，请按需修改 command。

验证是否连上

接入后应能看到 5 个工具：query_account_and_positions / query_deals / query_orders / place_order / cancel_order。可用 query_account_and_positions 做连通性验证（需浏览器已登录）。

工具

测试

.venv/Scripts/python.exe -m pytest -v            # 单元测试
PYTHONPATH=. .venv/Scripts/python.exe scripts/e2e.py        # 真实浏览器端到端（需已登录浏览器）
PYTHONPATH=. .venv/Scripts/python.exe scripts/mcp_smoke.py  # MCP stdio 协议冒烟

服务配置

项目根目录下 config.yaml：

• cdp_enpoint：Chrome 远程调试地址，默认 http://127.0.0.1:9222。若在 启动浏览器.bat 中修改了调试端口，需同步修改此项。

• slow_ms：慢速观察模式延时（见下节）。

• refresh_before_tool：每次 MCP 工具运行前是否先刷新交易页探测登录超时。 true（默认）= 每次调用先 reload 交易页检测会话，超时则自动关掉失效 tab、重进交易区； false = 走原始快速路径（仅右上角账户号异常时才刷新式探测）。 若 8/18 下单失败类问题复发（刷新后行情加载失效），可设 false 一键回退。

• delays：下单/撤单各步骤延时（毫秒），可按网络/平台情况针对性调大以提高成功率。 其中 quote_timeout 超时会不点击下单按钮、直接返回「下单失败：行情数据未加载…未提交委托」； js_settle 是刷新交易页后等待页面 JS 初始化完成的延时（默认 3000）。 未配置的键自动使用默认值（菜单 300 / 面板 800 / 行情与弹窗超时 8000 / 撤单生效 1000 / JS 就绪 3000）。

慢速观察模式

MCP 工具操作浏览器默认很快（1-2 秒跑完），不适合人工逐步骤观察核实。通过项目根目录 config.yaml 的 slow_ms 开启慢模式：每次浏览器操作之间延时该毫秒数，并在服务 stderr 日志中打印中文步骤（如「填写证券代码 600000 并按回车加载行情」「点击买入下单提交」）。

在 config.yaml 中把 slow_ms 改为 1200（每次操作停顿 1.2 秒），重启 MCP 服务会话即可生效：

# config.yaml
slow_ms: 1200

设为 0 即原速。用文件而非环境变量，是为了兼容各类不注入环境变量的 AI Agent 客户端。

已知限制

• 下单依赖平台后端行情服务；偶发返回「暂时不提供[柜台查询证券行情(B)]/后台查询证券代码(B) 功能的服务」——这是交易平台端临时故障，重试或稍后再试即可。

• 撤单仅在「委托」未成交时才能执行；已成交/已撤销委托不会出现在可撤列表中，cancel_order 会返回明确的提示。

目录结构

• server.py — MCP 服务入口（FastMCP, stdio）

• config.yaml — 服务配置（慢速观察模式等）

• .mcp.json — Claude Code 的 MCP 接入配置

• ths/ — 业务逻辑（浏览器控制、选择器、解析器、页面操作、错误）

• scripts/ — 勘察/端到端/协议冒烟脚本

• tests/ — 单元测试与真实页面 fixture