同花顺网页模拟交易 MCP 服务

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

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

• 本项目的MCP服务负责「账户持仓」「下单交易」
• 同花顺 iFinD AI 金融数据服务负责「查数据选股」「查行情指标」（同花顺有免费试用额度）。

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

重要提醒

• 先启动浏览器并登录同花顺交易系统（见「使用前提」），交易服务才能下单。
• 下单只支持市价，数量须为 100 的整数倍；买入前 AI 会先查资金，卖出前会先查持仓。
• AI炒股，各显神通，盈亏自负！，不要滥用本工具，更不能用于商业化。
• 本项目只能模拟炒股，如果交易策略得到验证想上线真实账户怎么办？请您联系作者会有解决方案！

使用前提

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 做连通性验证（需浏览器已登录）。

工具

工具	说明
query_account_and_positions	查看账户资金与持仓信息（可用余额、资金余额、总资产、证券市值等及持仓明细）
query_deals	查看当日成交
query_orders	查看当日委托
place_order	市价委托买入/卖出（direction/stock_code/quantity，数量为 100 的整数倍，仅市价单）
cancel_order	撤销未成交委托（order_id 为委托号）

测试

.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_endpoint：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