同花顺 Web Simulated Trading MCP Service

Encapsulates the 同花顺 trading system as a general-purpose MCP service (stdio) that various AI Agents can call.

Practical case study: two MCP services working together for fully automated stock trading

• This project's MCP service handles "account holdings" and "order placement/trading".

• The 同花顺 iFinD AI 金融数据服务 handles "data-driven stock screening" and "market quote/indicator queries" (同花顺 offers free trial credits).

Once both services are connected to the same AI Agent (such as hermes, codex, claude desktop, workbudy, trae work, and deepseek harness), you only need to tell the AI "trade stocks automatically using strategy XX". It will use iFinD to look up quotes and select stocks, then use the trading service to place orders, cancel orders, and check fills automatically — no manual account operation needed throughout.

Important notices

• Start the browser and log in first 同花顺 trading system (see "Prerequisites") before the trading service can place orders.

• Only market orders are supported, and quantity must be a multiple of 100. Before buying, the AI first checks your cash; before selling, it first checks your holdings.

• AI stock trading — each tool does its own thing, and you are solely responsible for profits and losses. Don't abuse this tool, and never use it commercially.

• This project is for simulated trading only. What if your strategy is proven and you want to go to live account? Please contact the author for a solution!

Related MCP server: QMT MCP Server

Prerequisites

1. Manually start the browser (see 启动浏览器.bat): Chrome with debug port 9222, using a dedicated user data directory chrome_profile.

2. Manually log in to 同花顺 trading system and enter the trading page.

3. Above conditions are met the MCP service can work normally; otherwise every tool returns a clear Chinese error message.

Environment

• Recommended Python version: 3.11 (mcp dependency reqires >=3.10; 3.10–3.12 all work fine).

• Python environment: .venv inside the project (virtual environment; creation covered in the next section).

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

• Notes: Playwright connects to the already-open browser via CDP, no browser kernel needs to be downloaded; it stores no account credentials, and fully relies on the manually logged-in session.

Create the Python virtual env

On first use, create .venv under the project root (choose one of the two methods):

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

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

After that install the dependencies:

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

On Windows the interpreter is .venv/Scripts/python.exe (on Linux/macOS: .venv/bin/python); all commands below assume .venv/Scripts/python.exe.

MCP configuration guide

This service runs over stdio transport, any MCP-capable client can connect. The core config is just one line: start server.py with the Python interpreter of the project's .venv.

Connection config (works for all AI Agents)

{
  "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"]
    }
  }
}

On Windows use forward slash paths D:/...; if your .venv lives elsewhere, adjust command.

Verify

After connecting you should see 5 tools: query_account_and_positions / query_deals / query_orders / place_order / cancel_order. Use query_account_and_positions for connectivity test (the browser must be logged in).

Tools

Testing

.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 协议冒烟

Service configuration

config.yaml in the project root:

• cdp_endpoint: Crochrome remote debugging address, default http://127..0.1:9222. If you change the debug port in 启动浏览器.bat, sync this setting.

• refresh_before_tool: whether to refresh the trading page to detect session timeout before each MCP tool run. true (default) = reload the trading page first and detect session, auto close stale tabs and re-enter trading area on timeout; false = old fast path (refresh only when account number whose reload indicates an issue). If 8/18 order-failure issues (quotes failing to load after refresh) recur, set false as a one-click rollback.

• delays: per-step delays in ms during ordering/canceling, you can tune them individually to improve success rate. If quote_timeout fires, it will NOT click the order button and just return "Order failed: quote data not loaded... pending order not submitted"; js_settle is delay to wait after an optional page reload JS init (default, 3000). Unconfigured keys automatically use defaults (menu 300 / panel 800 / quotes popup timeout 8000 / cancel permanent delay 1000 / JS ready 3000).

Slow observation mode

MCP tools operate browser very fast by default (1–2 seconds total), not friendly for human step-by-step watch and verify. via config.yaml's slow_ms you can enable slow-down mode: delay that many ms between each browser operation, and print Chinese step in your log (like "fill securities code 600000 and press enter to load quote", "click buy order submit").

In config.yaml set slow_ms to 1200, then restart the MCP service session:

# config.yaml
slow_ms: 1200

Set it to 0 to go back to original speed. Using a config file rather than Environment variable is to keep compatible with all AI Agent clients that don't support env variables.

Known limitations

• Placing order depends on platform back-end quote service; sometimes returns "temporarily no service[柜台 securities quote (B)]/back-end code (B)" — that's platform-side temporary fault, retry or try later.

• Cancellation only works while the order is "unfilled". Already-filled/cancelled orders don't show in the cancelable list, cancel_order returns a clear message.

目录结构

• server.py — MCP entry point (FastMCP, stdio)

• config.yaml — service config (slow observation mode etc.)

• .mcp.json — Claude integration entry config

• ths/ — business logic (browser control, selectors, parsing, page ops, errors)

• scripts/ — sabotage / end-to-end / protocol smoketest scripts

• tests/ — unit tests and real-page fixtures