tdx-link-mcp 0.8.2

通达信 AI Agent MCP Server - pip + 国内镜像安装，降低用户门槛

TdxLink — 通达信量化框架 + MCP Server

一个项目两种用法:AI Agent 通过 MCP 工具操作通达信,Python 开发者通过 tdx_lib 写量化策略。

适合谁看

你是	用什么	看哪段
AI Agent 用户(用 Cursor/Claude/Trae 等让 AI 操作通达信)	MCP Server	快速安装 + MCP 可用工具 + AI 调用时机
Python 开发者(自己写选股/交易/回测策略)	tdx_lib 框架	框架架构 + 快速上手
项目维护者(改代码/发版)	全部	目录结构 + PUBLISH_GUIDE.md

---

快速安装(MCP Server)

方式一:通过 AI 平台安装(最简,推荐)

把下面这段复制给你正在用的 AI Agent,它只需要执行两条命令:

帮我安装 TdxLink MCP Server(通达信 AI Agent)。

请依次执行以下命令:

第一步 - 安装包(使用国内镜像加速):
pip install --upgrade tdx-link-mcp -i https://pypi.tuna.tsinghua.edu.cn/simple

第二步 - 配置 MCP:
python -m tdx_link_mcp.setup_mcp

完成后告诉我结果。

为什么用 pip 而不是 uvx？

• pip 是 Python 标配，AI 编码平台自带，无需额外安装
• 清华镜像在国内，下载速度快（vs uvx 从国外服务器下载）
• 安装后直接 python -m 运行，简洁稳定

支持平台: Trae, Cursor, Claude Code, VS Code/Copilot, Gemini CLI, OpenCode, OpenClaw, Cline, Kimi CLI, Pi Agent, Codex CLI, Antigravity, Windsurf, Mistral Vibe, Qoder（共 16 个）

方式二:一键脚本安装

Windows(PowerShell):

powershell -c "irm https://raw.githubusercontent.com/JueJuez/tdxLinkMcp/main/install.ps1 | iex"

Mac/Linux:

curl -fsSL https://raw.githubusercontent.com/JueJuez/tdxLinkMcp/main/install.sh | bash

脚本会自动:检测 Python → 用国内镜像安装包 → 检测已装的 AI 工具 → 写入 MCP 配置。

方式三:手动安装(高级用户)

1. 安装包

# 使用清华镜像(推荐，国内速度快)
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple tdx-link-mcp

# 或使用阿里镜像
pip install -i https://mirrors.aliyun.com/pypi/simple tdx-link-mcp

2. 配 MCP

在 AI 工具的 MCP 配置中添加:

{
  "mcpServers": {
    "tdxLink": {
      "command": "python",
      "args": ["-m", "tdx_link_mcp.server"]
    }
  }
}

配置文件位置(常用平台):

• Trae:~/.trae/User/mcp.json(Windows: %APPDATA%\Trae CN\User\mcp.json)
• Cursor:~/.cursor/mcp.json
• Claude Code/Desktop:~/.claude/claude_desktop_config.json(Windows: %APPDATA%\Claude\claude_desktop_config.json)
• VS Code:~/.vscode/mcp.json
• OpenCode:~/.config/opencode/opencode.json(注意:键名是 mcp 不是 mcpServers)
• 其他:Cline / Kimi CLI / Pi Agent / Codex CLI / Gemini CLI / Antigravity / Windsurf / Qoder / Mistral Vibe

如果配置文件已有其他 MCP,把 tdxLink 合并进 mcpServers 对象,不要覆盖整个文件。 非标准格式(OpenCode/OpenClaw/Mistral Vibe)建议直接用 python -m tdx_link_mcp.setup_mcp 自动处理。

3. 重启 AI 工具

---

备选安装方式(uvx)

如果 pip 安装失败，可以尝试 uvx 方式:

uvx tdx-link-mcp --upgrade

uvx 会自动管理 Python 环境，适合没有 Python 的机器。但需先安装 uv 工具:

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Mac/Linux  
curl -LsSf https://astral.sh/uv/install.sh | sh

---

MCP 可用工具

装好后,AI 会自动发现 12 个工具:

工具	功能	底层模块
get_market_info	行情查询（快照/K线/基础信息/搜索）	tdx_lib
screen_stocks	选股（涨跌停/自定义公式）	tdx_lib
get_financial_info	财务数据查询	tdx_lib
manage_portfolio	板块管理（增删改查/预警）	tdx_lib
execute_trade	下单/撤单/持仓查询	tdx_lib
get_market_stats	市场统计（涨跌家数）	tdx_lib
ensure_tdx_ready	通达源自启动	tdx_lib
run_backtest	策略回测（全参数化自定义，50+ 条件参数 + 60+ 口语速查表）	tdx_lib.backtest
manage_risk	风险管理（止损止盈/仓位计算/组合风控）	tdx_lib.risk
setup_grid_trading	网格交易配置（等差/等比/买卖信号）	tdx_lib.grid
schedule_strategy	定时策略调度（定时执行/CRON表达式）	tdx_lib.scheduler
check_version	版本检查（当前版本 vs PyPI 最新版本）	tdx_link_mcp.version_check

使用示例

你: 帮我查今天涨停的股票
AI: [调用 screen_stocks(limit_up)] → 返回涨停股列表

你: 查贵州茅台的财务数据
AI: [调用 get_financial_info(codes=["600519.SH"])] → 返回财务信息

你: 买入100股贵州茅台
AI: [调用 execute_trade(buy, code="600519.SH", quantity=100)] → 执行交易

你: 帮我回测一个策略：近8日有涨停，回调不破实体50%，缩量，站上MA5
AI: [调用 run_backtest(conditions={limit_up_lookback:8, pullback_body_ratio:50, ...})] → 回测报告

AI 调用时机

外部 AI 首次连接时，请先读取 MCP Resource SKILL_USER.md，内有完整的工具使用指南、防呆规则和决策树。

当用户在 AI 会话中询问以下问题时，会优先调用 TdxLink MCP：

• 股票行情查询
• 股票筛选（涨停/跌停）
• 财务数据分析
• 板块管理
• 交易操作
• 市场统计
• 策略回测（口语描述策略→AI 自动转参数执行）
• 风险管理（止损止盈/仓位计算）
• 网格交易配置
• 定时策略调度

调用示例

# 获取茅台实时行情
get_market_info(info_type="snapshot", codes=["600519.SH"])

# 筛选涨停股票
screen_stocks(screen_type="limit_up")

# 获取茅台财务数据
get_financial_info(codes=["600519.SH"], data_type="financial")

# 策略回测 — 口语描述即可，AI 自动转为参数
run_backtest(conditions={
    "limit_up_lookback": 8,
    "pullback_body_ratio": 50,
    "volume_shrink_ratio": 60,
    "require_close_above_ma": [5],
    "ma_trend_up": [20, 60],
})

# 风险管理
manage_risk(action="calculate", capital=100000, price=10.0, stop_loss_pct=5.0)

测试建议(从无副作用到有副作用)

1. ensure_tdx_ready — 确认客户端就绪
2. get_market_stats(stat_type=limit_count)— 秒查涨跌停家数
3. get_market_info(info_type=snapshot, codes=["600519.SH"])— 单只快照
4. get_market_info(info_type=kline, kline_count=10)— K线
5. get_market_info(info_type=search, key_word="茅台")— 搜索
6. screen_stocks(screen_type=limit_up)— 涨停筛选(全市场约 2s)
7. get_financial_info(data_type=financial, codes=["600519.SH"])— 财务
8. manage_portfolio(action=query)— 查所有自定义板块(只读)
9. execute_trade(action=query_asset)— 查资产(只读,要交易端登录)
10. run_backtest(conditions={...})— 策略回测（口语描述→参数，无副作用）
11. manage_risk(action=calculate)— 仓位/止损计算（只读）
12. setup_grid_trading(action=status)— 网格状态查询（只读）
13. 最后才碰有写副作用的:manage_portfolio 的 create/send/clear、execute_trade 的 buy/sell。交易务必小额先试。

---

框架架构

下面是给 Python 开发者看的。如果你只用 MCP,跳过即可。

┌──────────────────────────────────────────────────────────┐
│                    strategies/  策略层                      │
│        用户只写这里: 继承 StrategyBase, 实现 analyze()       │
├──────────────────────────────────────────────────────────┤
│           strategy.py        backtest.py    scheduler.py  │
│           策略生命周期        回测引擎       定时调度        │
├──────────────────────────────────────────────────────────┤
│  data.py      trade.py     portfolio.py   risk.py  grid.py│
│  行情数据     交易下单      板块管理      风控止损  网格交易  │
├──────────────────────────────────────────────────────────┤
│              client.py              utils.py              │
│              HTTP通信               计算工具               │
└──────────────────────────────────────────────────────────┘

设计原则:策略层只依赖框架层,框架层只依赖服务层,服务层只依赖基础层。换策略不用改基础设施,加功能不用动底层通信。

功能清单

模块	功能	状态
client.py	HTTP JSON-RPC 通信、批量并发调用、连通性检测	✅
launcher.py	通达信进程检测/自动拉起/HTTP就绪轮询(一行调用)	✅
data.py	股票列表、K线、快照、more_info 批量查询、预筛框架	✅
financial.py	官方财务/交易数据9接口(FN/GP/BK/SC/GO系列),透传官方	✅
screener.py	通用筛选器(透传官方公式B007判定涨跌停,取数优化)、涨跌停家数秒查	✅
selector.py	官方公式选股(B007),与客户端"条件选股"一致	✅
guard.py	官方优先守卫,运行时强制官方入参	✅
trade.py	买入/卖出/市价/限价/涨跌停价/隔夜挂单/批量撤单/账户查询	✅
portfolio.py	板块创建/删除/清空/重写、预警信号、客户端跳转	✅
strategy.py	策略基类,串联完整生命周期(选股→预筛→分析→输出→写板块)	✅
custom_strategy.py	全参数化自定义策略，50+ 条件参数，AI 无需写策略类	✅
risk.py	止损(固定/移动/ATR)、止盈(固定/移动)、仓位管理(固定/比例/凯利)	✅
grid.py	网格交易(等差/等比),自动低买高卖	✅
backtest.py	历史回测(全参数化),绩效统计(胜率/回撤/夏普/盈亏比)	✅
scheduler.py	定时执行策略,支持 HH:MM 和 cron 表达式	✅

MCP Server 暴露 12 个工具，覆盖行情/筛选/财务/板块/交易/统计/启动/回测/风控/网格/调度/版本检查全部能力。

---

快速上手

1. 选股策略 — 只写 analyze()

# strategies/my_strategy.py
from tdx_lib import StrategyBase, calc_ma, parse_kline_float

class MyStrategy(StrategyBase):
    name = "我的策略"
    block_code = "MINE"
    min_cap = 50
    max_cap = 500

    def analyze(self, code, kline_data):
        parsed = parse_kline_float(kline_data)
        closes = parsed["Close"]
        if len(closes) < 20:
            return None
        ma5 = calc_ma(closes, 5)
        ma20 = calc_ma(closes, 20)
        if ma5 > ma20 and closes[-1] > ma5:
            return {"code": code, "close": round(closes[-1], 2)}
        return None

运行: python run_strategy.py my_strategy

2. 回测 — 全参数化，无需写策略类

from tdx_lib.backtest import BacktestEngine
from tdx_lib.custom_strategy import CustomStrategy

# AI 将策略条件转为参数即可回测，无需写 Python 类
conditions = {
    "limit_up_lookback": 8,             # 近8日有涨停
    "pullback_body_ratio": 50,          # 回调不破实体50%
    "volume_shrink_ratio": 60,          # 缩量至60%
    "require_close_above_ma": [5],      # 站上MA5
    "ma_trend_up": [20, 60],            # MA20/MA60向上
    "require_yang_line": True,          # 今日收阳
    "min_market_cap": 30,               # 市值≥30亿
    "max_market_cap": 300,              # 市值≤300亿
}

engine = BacktestEngine(
    CustomStrategy,
    initial_capital=1_000_000,
    conditions=conditions,
)
engine.stop_loss_pct = -5.0
engine.take_profit_pct = 10.0
engine.trailing_stop = True
report = engine.run(start_offset=60, stock_limit=200)
engine.print_report()

3. 交易 + 止损止盈

from tdx_lib import TdxClient, TdxTrader, RiskManager, StopLoss

client = TdxClient()
trader = TdxTrader(client)
rm = RiskManager(stop_loss_type=StopLoss.Type.TRAILING, sl_pct=5.0,
                 capital=trader.get_total_asset())

# 买入
volume = rm.calc_volume(price=10.0)
trader.limit_buy("600000", volume, 10.0)
rm.on_buy("600000", 10.0)

# 检查止损
should_exit, exit_price, reason = rm.check_exit("600000", high=10.5, low=9.6)

4. 网格交易

from tdx_lib import GridTrader

grid = GridTrader("600000", lower_bound=8, upper_bound=12,
                  grid_count=20, volume_per_grid=200)
grid.setup(current_price=10.0)

actions = grid.on_price_update(current_price=10.5)
# → [{"action": "sell", "price": 10.5, "volume": 200, ...}]

5. 定时自动运行

from tdx_lib import StrategyScheduler

sched = StrategyScheduler()
sched.add_strategy("my_strategy", time_str="15:30")  # 每天15:30选股
sched.add_task(overnight_orders, time_str="14:50", name="隔夜挂单")
sched.run()

6. 条件筛选 — 涨跌停/涨幅/市值(两层过滤,秒级)

from tdx_lib import TdxClient, StockScreener, get_market_limit_count

client = TdxClient()

# 秒查涨跌停家数 (1次请求, ~0.005s)
r = get_market_limit_count(client)
print(f"涨停 {r['limit_up']} 家, 跌停 {r['limit_down']} 家")

# 涨停明细 (粗筛涨幅 + 精筛触及涨停价, 全市场 ~2s)
results = (StockScreener.from_all_a_stocks(client)
           .where(min_pct=9.8).limit_up().run())

# 任意条件: 涨幅 5-10% 且市值 30-300亿
results = (StockScreener.from_all_a_stocks(client)
           .where(min_pct=5.0, max_pct=10.0)
           .where(min_cap=30, max_cap=300).run())

运行策略

# 列出所有可用策略
python run_strategy.py

# 运行指定策略
python run_strategy.py first_board_pullback
python run_strategy.py macd_cross

策略文件放入 strategies/ 目录后自动注册,文件名即策略名。

---

目录结构

tdxLinkMcp/
├── tdx_lib/                        # 核心框架(本地脚本直接 import)
│   ├── __init__.py                 # 统一导出
│   ├── client.py                   # HTTP 客户端
│   ├── utils.py                    # 工具函数
│   ├── launcher.py                 # 客户端启动器
│   ├── data.py                     # 行情数据
│   ├── financial.py                # 官方财务/交易数据
│   ├── screener.py                 # 通用筛选器
│   ├── selector.py                 # 官方公式选股 (B007)
│   ├── guard.py                    # 官方优先守卫
│   ├── trade.py                    # 交易接口
│   ├── portfolio.py                # 板块管理
│   ├── risk.py                     # 风险管理
│   ├── grid.py                     # 网格交易
│   ├── strategy.py                 # 策略基类
│   ├── custom_strategy.py          # 全参数化自定义策略
│   ├── backtest.py                 # 回测引擎
│   └── scheduler.py                # 定时调度
├── strategies/                     # 策略目录
│   ├── first_board_pullback.py     # 首板回调捉妖
│   └── macd_cross.py               # MACD金叉
├── src/tdx_link_mcp/               # MCP Server (PyPI 包)
│   └── server.py                   # 12 个 MCP 工具注册
├── tests/                          # 单元测试
├── run_strategy.py                 # CLI 运行入口
├── SKILL_USER.md                   # AI 使用指南（外部 AI：MCP 工具 + 防呆规则）
├── SKILL_DEV.md                    # AI 开发文档（内部维护：API 签名 + 策略指南）
├── PUBLISH_GUIDE.md                # 发版维护指南
├── install.ps1 / install.sh        # 一键安装脚本(Shell)
├── setup_mcp.py                    # 一键安装工具(Python, AI 调用入口)
└── README.md                       # 本文件

---

前置条件 & 依赖

• Python 3.10+(MCP 通过 uv 自动管理,无需手动装)
• 通达信客户端:必须在本地运行(Windows),并开启 HTTP 服务(默认端口 17709)
• 交易接口:需通达信已登录交易终端
• 框架本身无第三方依赖(纯标准库),MCP Server 依赖 httpx + mcp(uv 自动装)

---

常见问题

Q: 提示"无法连接通达信"? A: 确保通达信客户端已启动且 HTTP 服务已开启(默认端口 17709)。

Q: 可以远程使用吗? A: 当前仅支持本地使用(通达信客户端必须在本地运行)。

Q: 支持哪些 AI 工具? A: 所有支持 MCP 协议的工具。setup_mcp.py 已内置 15 个平台自动配置: Trae、Cursor、Claude Code、VS Code+Copilot、OpenCode、OpenClaw、Cline、 Kimi CLI、Pi Agent、Codex CLI、Gemini CLI、Antigravity、Windsurf、Qoder、Mistral Vibe。

Q: 如何更新到最新版本? A: 配置中已启用 --upgrade,每次启动 AI 工具会自动检查。手动更新:uv cache clean tdx-link-mcp。

Q: 安装后没有生效? A: 重启 AI 工具,确保配置文件已正确写入。

Q: MCP 工具和 tdx_lib 框架是什么关系? A: MCP 是 tdx_lib 的子集封装。框架 14 个模块里 12 个被封装成 MCP 工具(给 AI 用);策略框架 StrategyBase 只给本地 Python 用(写自定义策略类)。

---

开发者说明

本地开发测试

# 克隆项目
git clone https://github.com/JueJuez/tdxLinkMcp.git
cd tdxLinkMcp

# 安装依赖
pip install -e .

# 运行测试
python -m pytest tests/

# 本地启动 MCP Server(用于调试)
python -m tdx_link_mcp.server

相关文档

文档	给谁看	内容
README.md(本文件)	所有人	安装 + 框架介绍
SKILL_USER.md	外部 AI 模型	MCP 工具使用指南 + 防呆规则 + 决策树（严禁读源码）
SKILL_DEV.md	项目维护者 AI	框架 API 签名、策略编写指南、回测与风控说明
PUBLISH_GUIDE.md	维护者	发版到 PyPI 的步骤

项目铁律(给 AI 的话)

首要原则: 官方入参优先。 用户与 AI 沟通形成的策略/条件,最终必须是通达信官方接口的入参,本框架只取数与呈现。详见 .trae/rules/official-first.md(项目铁律,由 tdx_lib/guard.py 运行时强制)。

涨跌停判定必须走 TdxSelector(官方公式 B007),禁止本地 ZAF 阈值。

如果需要修改、扩展、或添加新功能,请先读 SKILL_DEV.md — 它是 API 速查与操作指南。

发布到 PyPI

见 PUBLISH_GUIDE.md。

---

版本历史

• v0.8.0 (2026-07-04):接口核查修复 + 文档管理规范化
  • screen_stocks 工具 description 补全 107 个官方选股公式（按 16 类分组，形态类 24 个全列）
  • 新增口语同义名标注（如 YYD 鸳鸯底（口语: 双底/W底）），消除 AI 因"官方名≠口语名"自写代码
  • screen_stocks 新增 stock_period/count/dividend_type 参数（支持周线/月线/复权选股）
  • manage_portfolio 修复 down_type 文档值错误（1=十大股东，非龙虎榜）+ 新增 stock_code 参数
  • execute_trade 新增 account_type（STOCK/CREDIT 信用账户）
  • setup_grid_trading 新增 total_capital/base_position_ratio/reset action
  • schedule_strategy 新增 trading_days_only + 7 个预设时间点（PRE_OPEN/MARKET_OPEN/PRE_CLOSE/POST_CLOSE 等）
  • run_backtest 新增形态条件命名对照（double_bottom = YYD 鸳鸯底）
  • 文档管理规范化：docs/README.md 规则 + active/archive/reference 三级目录 + 失实文档标记 obsolete
• v0.5.1 (2026-07-02):文档拆分 + 防呆加固
  • SKILL.md 拆分为 SKILL_USER.md（外部 AI 用户指南，含防呆规则 + 决策树）+ SKILL_DEV.md（内部开发者文档）
  • MCP Resource 改为暴露 SKILL_USER.md，防止外部 AI 读取源码文档后绕过 MCP 自写脚本
  • 增强 MCP 工具描述：manage_portfolio/execute_trade/run_backtest/screen_stocks 加入防呆提示
  • 新增 6 条防呆规则：意图不明反问、条件矛盾纠错、前置步骤检查、危险操作确认、类型检查、禁止行为清单
• v0.5.0 (2026-07-02):回测全面重构 + 策略条件扩展 + 自然语言速查表
  • run_backtest 全面重构: 移除固定策略，改为全参数化自定义模式，新增 CustomStrategy 类
  • 策略条件从 18 个扩展到 50+ 个，覆盖 MACD/KDJ/RSI/布林带/形态/箱体/均线/换手率等 12 组
  • utils.py 新增 8 个技术指标计算函数（EMA/MACD/KDJ/RSI/布林带/均线方向）
  • MCP 工具描述新增 60+ 条自然语言→参数速查表，AI 直接映射用户口语到策略参数
  • get_market_info/get_financial_info 新增字段编码速查表，AI 可将中文需求转为字段编码
  • 新增 docs/category.txt，22 个标准策略场景全部可映射到 MCP 参数
  • MCP 工具从 7 个扩展到 11 个（run_backtest/manage_risk/setup_grid_trading/schedule_strategy）
• v0.3.1 (2026-07-01):优化发布流程 + 清理旧包缓存
  • 优化 PyPI 发布流程，支持持久化验证 venv
  • 清理本地 pip 缓存，移除旧版本残留
  • 修复安装后 import 验证问题
• v0.3.0 (2026-06-30):官方优先强制机制 + 财务数据接口完善
  • tdx_lib/guard.py 官方优先守卫上线，运行时强制官方入参
  • 完善财务数据 9 接口（FN/GP/BK/SC/GO系列），透传官方数据
  • TdxSelector 涨跌停判定走官方公式 B007，禁止本地 ZAF 阈值
• v0.2.0 (2026-06-29):功能完善 + 策略框架
  • 新增策略框架、回测引擎、风险管理、网格交易、定时调度
  • MCP 工具扩展到 7 个
• v0.1.5 (2026-06-29):权限自动提权 + 智能缓存目录
  • UAC 提权机制：MCP Server 启动时自动检测权限，权限不足时请求 UAC 提权
  • 智能缓存目录检测：自动检测可写的缓存目录，避免权限拦截
  • 优先使用用户主目录（%USERPROFILE%\.uv-cache），降级到临时目录
  • 完全自动化安装流程，用户无需手动配置
• v0.1.2 (2026-06-28):一键安装工具 + 多平台支持
  • 新增 setup_mcp.py:Python 一键安装工具,AI 只需执行一条命令即可完成全部安装
  • 支持 15 个 AI 编码平台自动配置:Trae/Cursor/Claude/VS Code/OpenCode/OpenClaw/ Cline/Kimi/Pi/Codex/Gemini/Antigravity/Windsurf/Qoder/Mistral Vibe
  • 智能合并不覆盖已有 MCP 配置(解决旧脚本覆盖用户配置的问题)
  • 支持 3 种配置格式:标准 JSON mcpServers / OpenCode mcp 键 / Mistral Vibe TOML
  • 修复 install.ps1 中 Trae 配置路径错误 + 改为合并写入
  • 解决 AI 逐步安装需 5-10 分钟的问题(脚本 30-60 秒完成)
• v0.1.1 (2026-06-27):修复打包 bug
  • 修复:打包后 from tdx_lib import 找不到模块(v0.1.0 用户安装后无法启动)
  • 改为单一真源:tdx_lib 作为独立顶级包打包,删除 src 下拷贝
  • 文档重组:README 合并 MCP_README,删除 3 个冗余文档
• v0.1.0 (2026-06-27):首次发布
  • 7 个场景化 MCP 工具
  • 14 个 tdx_lib 框架模块
  • 支持 Trae/Qoder/Cursor/Claude Desktop
  • 全自动安装脚本

---

许可证

MIT License