Wechat Devtools Mcp

io.github.WaterTian由 GitHub 帳號 WaterTian 發布v0.9.20更新於 Oct 26, 2026

MCP Server for WeChat DevTools CLI - Automate development & testing with 7 aggregated APIs.

已驗證STDIO僅桌面瀏覽器自動化開發者工具

概覽

AI 產生的概覽

封裝微信開發者工具 CLI，讓助手在編輯器內完成小程式的編譯、預覽、上傳、自動化互動與除錯。

可以做什麼
  • 開啟、掃碼登入、關閉或結束微信開發者工具，並做環境診斷
  • 編譯、預覽、上傳小程式，建置 npm 與清除快取
  • 操作模擬器：點擊、輸入、設定資料、呼叫方法與 wx API、Mock wx、執行 JS，查詢頁面堆疊、頁面資料、系統資訊與快取
  • 蒐集執行時 console 日誌與 JS 例外，以及 CDP 層的 WXML 警告與渲染錯誤
  • 擷取模擬器畫面截圖，支援自動捲動拼接長圖
  • 跳轉指定頁面並蒐集 CDP 日誌，讀取專案資訊、頁面清單與原始碼檔案
適用情境
適合開發或測試微信小程式時，讓助手直接跑完編譯、預覽、上傳與模擬器測試流程，不必切回 IDE。也適合頁面生命週期日誌檢查，以及官方內建 MCP 未涵蓋的長圖截圖。
執行需求
本機程序，以 uvx 執行；需要 Python 3.10 以上（由 uv 準備）、Node.js 18 以上，以及微信開發者工具 2.x 或 1.06.x，僅支援 Windows 或 macOS。需在開發者工具安全設定中開啟服務埠。必填環境變數 WECHAT_DEVTOOLS_CLI 與 WECHAT_PROJECT_PATH；選用 WECHAT_CDP_PORT、WECHAT_CLI_TIMEOUT、WECHAT_AUTOMATOR_READY_TIMEOUT 與 NODE_PATH。搭配的 Skill 需另外安裝。
安裝前請注意
上傳動作會發佈小程式，自動化動作會點擊、輸入並修改模擬器資料，因此一次對話請求就可能造成寫入或發版。需填寫開發者工具 CLI 與專案目錄的本機絕對路徑，並開啟服務埠，擴大了本機存取面。README 提醒官方 IDE 註冊了名稱相近的 bridge，命名衝突可能讓工具走錯；部分用戶端的自動核准清單會讓七個工具不經確認直接執行。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Wechat Devtools Mcp，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

微信开发者工具 MCP Server (v0.9.20)

[PyPI version] [MCP Registry] [License: MIT] [English]

把微信开发者工具封装为 MCP 服务，让编辑器里的 AI 直接完成小程序的编译、预览、调试、自动化测试闭环。Windows / macOS，已上架官方 MCP Registry。

[!IMPORTANT] 「瘦 MCP + 胖 Skill」：MCP Server 只提供 7 个聚合工具，操作流程与最佳实践都在配套的 wechat-devtools Skill 里。两者必须一起装。

🤝 与官方能力的关系

微信开发者工具 2.x 自 2026-08-18 起为官方 Stable（1.06 已下架），IDE 内建 MCP Server（47 个原子工具，其中 2 个已废弃）。两者互补，不是替代：

场景用谁
打开项目 / 编译 / 预览 / 上传 / 点击输入 / 云开发2.x 优先官方内建 MCP（wechat_ide(action='status') 的 official_mcp.available 为 true 即可用）
长图拼接截图（固定头尾识别，拍不全如实上报）本项目。官方只截视口并压到长边 1280 JPEG
CDP 结构化日志（回放采集前的历史、按页面归类、去噪）本项目。官方只读缓存
任务级 SOP（一句话跑完巡检 / 异常排查 / 跨页面校验）本项目 Skill
存量 1.06.x（NW.js）本项目继续兼容；官方内建 MCP 仅 2.x 有

⚠ 官方 IDE 把自家 bridge 注册为 wechat-devtools。本文示例统一用 wechat-devtools-mcp 避免撞名；旧名配置仍可用，只在同一 agent 同时接入两者时才需区分。

🚀 快速开始

前置条件：Python ≥ 3.10（uv 会自动准备）、Node.js ≥ 18（daemon 依赖 puppeteer-core / jimp）、微信开发者工具 2.x 或 1.06.x。

Step 1 — 安装 MCP Server

bash
pip install uv                                           # 或 brew install uv；已装可跳过uv tool install wechat-devtools-mcp                      # 首次安装uv tool install wechat-devtools-mcp --force --refresh    # 升级：--refresh 刷新索引缓存，否则可能装回旧版wechat-devtools-mcp --version                            # 确认实际运行版本

[!WARNING] 曾用 pip install 装过旧版的，先 pip uninstall wechat-devtools-mcp，否则旧路径优先于 uv。 ≤0.9.10 与 mcp SDK ≥2.0 不兼容（报 ModuleNotFoundError: mcp.server.fastmcp），请升到 ≥0.9.11。

升级前先停掉编辑器里正在跑的 MCP 进程（重启编辑器即可）。用 uvx 配置的客户端会复用已缓存的环境、不会自动升级：跑一次 uvx --refresh wechat-devtools-mcp --version 刷新，或在 args 里锁定版本 wechat-devtools-mcp==X.Y.Z。

Step 2 — 开启开发者工具服务端口

开发者工具 → 设置 → 安全设置 → 服务端口 → 开启。不开则 open / compile / preview 等走 CLI 的操作全部报 CLI_TIMEOUT。

Step 3 — 准备两个绝对路径

路径WindowsmacOS
开发者工具 CLIC:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat/Applications/wechatwebdevtools.app/Contents/MacOS/cli
小程序项目根目录D:\MyProjects\mini-app/Users/<you>/Projects/mini-app

JSON 里 Windows 路径的 \ 要写成 \\；macOS 的 / 不用转义。

Step 4 — 编辑器配置

标准配置（Claude Desktop / Antigravity / Kiro / Trae / Claude Code .mcp.json 通用）：

json
{  "mcpServers": {    "wechat-devtools-mcp": {      "command": "uvx",      "args": ["wechat-devtools-mcp"],      "env": {        "WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat",        "WECHAT_PROJECT_PATH": "D:\\Your\\Project\\Path"      }    }  }}

9222 常年被 Chrome 等占用的机器，在 env 里再加一行 "WECHAT_CDP_PORT": "9333"。

编辑器配置位置差异
Claude Desktop / Antigravityclaude_desktop_config.json / mcp_config.json无
Claude Code（项目级）仓库根目录 .mcp.jsonuvx 走终端 PATH 即可。若编辑器是 GUI 启动（桌面版）报找不到 uvx / node，command 改绝对路径 /opt/homebrew/bin/uvx，并在 env 加 "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin" 与 "NODE_PATH": "/opt/homebrew/bin/node"
Kiro~/.kiro/settings/mcp.json可加 "autoApprove": ["wechat_ide","wechat_build","wechat_automator","wechat_inspector","wechat_screenshot","wechat_navigate","wechat_file"]
Trae ≥1.3AI 面板 → 设置 → MCP → 手动配置；或 %APPDATA%\Trae\User\globalStorage\mcp.json / ~/Library/Application Support/Trae/User/globalStorage/mcp.json聊天须选 Builder with MCP 智能体；macOS 报找不到 uvx 时同上改绝对路径
Cursor / VS CodeMCP 面板新增 serverName wechat-devtools-mcp，Command uvx wechat-devtools-mcp，环境变量同上
OpenAI Codex~/.codex/config.tomlTOML，见下
toml
[mcp_servers.wechat-devtools-mcp]command = "uvx"args = ["wechat-devtools-mcp"]
[mcp_servers.wechat-devtools-mcp.env]WECHAT_DEVTOOLS_CLI = "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat"WECHAT_PROJECT_PATH = "D:\\Your\\Project\\Path"

Step 5 — 安装 Skill（必须）

bash
npx -y skills add WaterTian/wechat-devtools-mcp/.agents/skills/wechat-devtools

不走 npx skills 的客户端（如 Trae）：把仓库的 .agents/skills/wechat-devtools/ 整个复制到小程序项目的 .agents/skills/ 下即可。Skill 含 9 条 SOP、7 工具全 action 速查、CDP 渐进排查策略与故障手册，详见 SKILL.md。

Step 6 — 自检

在编辑器里调一次 wechat_ide(action='status')，下面几项都符合再开工：

字段期望不符时
cli_exists / project_exists / node_availabletrue核对 Step 3 的两个路径；安装 Node.js ≥ 18
service_port_enabledtrue见 Step 2
cdp_port_occupant.kindnone 或 ideforeign 表示端口被别的浏览器占着，设 WECHAT_CDP_PORT=9333
skill_version等于 mcp_version重跑 Step 5 更新 skill 副本

🛠️ 工具箱

工具用途action / 关键参数
wechat_ideIDE 生命周期与环境诊断open login is_login close quit status
wechat_build构建与发布compile preview upload build_npm cache_clean
wechat_automator自动化交互与运行时查询start tap input element_info set_data call_method call_wx mock_wx evaluate page_stack page_data system_info storage
wechat_inspector运行时日志采集console cdp
wechat_screenshot长图拼接截图full_page page_path scroll_top
wechat_navigate跳转并采集 CDP 日志page_path
wechat_file项目文件读取project_info list_pages read_page read_file

动作遇到 automator 连接失败会自动 start 一次并重试（返回 auto_recovered）；open 成功后 cdp_port 在同一会话内自动沿用，其它工具不必再传。完整参数见 MCP_DOC.md。云函数与云数据库请用 CloudBase MCP。

💡 环境变量

变量说明默认
WECHAT_DEVTOOLS_CLI开发者工具 CLI 路径（必填）—
WECHAT_PROJECT_PATH默认项目根目录（必填）—
WECHAT_CLI_TIMEOUTCLI 超时秒数30
WECHAT_CDP_PORTCDP 调试端口默认值。9222 常被 Chrome 占用时设成 9333；open 成功后同会话其它工具自动沿用9222
WECHAT_AUTOMATOR_READY_TIMEOUTstart 等待 automator 首次应答的秒数，大项目冷启动可加大45
NODE_PATHNode.js 可执行文件node

❓ 常见问题

症状处理
一直报 CLI_TIMEOUT服务端口没开，见 Step 2；wechat_ide(action='status') 的 service_port_enabled 可自查
CDP 采集失败 / 采到的全是别的网页status 的 cdp_port_occupant.kind 为 foreign 即端口被别的浏览器占着：open(cdp_port=9333) 或设 WECHAT_CDP_PORT，之后其它工具不传端口自动沿用。0.9.19 起 open 会直接报错，不再把别人的页面报错当启动错误
automator 9420 连不上 / start 返回 verified=false0.9.19 起动作失联会自动 start 一次并重试；start 自带最多 45 秒就绪等待（ready_timeout 可调）。仍失败看 status 的 project_window_open，窗口被关就再 start，不要先 open 重启 IDE
Windows 中文乱码或 UnicodeDecodeErrorenv 加 "PYTHONIOENCODING": "utf-8"
装了新版仍跑旧版pip uninstall wechat-devtools-mcp；uvx 方式跑 uvx --refresh wechat-devtools-mcp --version；最后以 status 的 mcp_version 为准
IDE 2.x 下工具行为异常注册名与官方 wechat-devtools 撞车，改用 wechat-devtools-mcp

📋 版本历史

版本日期摘要
0.9.202026-10-26call_wx 同步 wx API 自动经 evaluate 直调，不再 10 秒超时；README / MCP_DOC / SKILL 逐字段核对修正；Node.js ≥ 18 门槛明示
0.9.192026-10-26automator start 按截止时间等就绪，根治「握手未完成」误报；CDP 端口占用检测与会话粘性（WECHAT_CDP_PORT）；automator 失联自动恢复；status 新增项目窗口 / skill 版本诊断
0.9.182026-09-04Windows 2.x 真机闭环：状态目录 User Data 层、就绪判据、quit 等退出、噪音过滤；新增真机冒烟脚本
0.9.172026-09-03适配开发者工具 2.x Stable；evaluate 新增 fn_source；open 提速约 4 倍；Windows 1.x/2.x 双轨判定
0.9.162026-08-27长页面截图全面修复；源码开源
0.9.152026-08-20适配开发者工具 2.x（Electron）；修复 CDP 采集自 0.9.0 起恒为 0 条
0.9.142026-08-20wechat_file 路径口径统一；cdp_port 透传修复
0.9.132026-08-18--version 早退；文档核对修复

完整逐版本说明见 CHANGELOG.md。

参考

來源：README.md，提交 2d1a214

工具

7

wechat_ide

IDE 生命周期管理

微信开发者工具 IDE 生命周期管理。 支持 action: open(打开IDE/项目), login(扫码登录), is_login(检查登录), close(关闭项目), quit(退出IDE), status(环境诊断)。 返回 JSON: {success, data, message, error_code?}。

輸入參數params必填

wechat_build

构建与发布

构建、预览、上传小程序及 npm 管理。 支持 action: compile(编译检查), preview(预览), upload(上传), build_npm(构建NPM), cache_clean(清缓存)。 返回 JSON: {success, data, message, error_code?}。

輸入參數params必填

wechat_automator

自动化交互

小程序自动化交互与运行时查询。 支持 action: start(开启自动化), tap(点击), input(输入), element_info(元素信息), set_data(设置数据), call_method(调用方法), call_wx(调用wx API), mock_wx(Mock wx), evaluate(执行JS), page_stack(页面栈), page_data(页面数据), system_info(系统信息), storage(缓存)。 返回 JSON: {success, data, message, error_code?}。

輸入參數params必填

wechat_inspector

运行时日志采集

采集小程序运行时日志和异常。 支持 action: console(automator端口采集console日志和JS异常), cdp(通过CDP协议采集WXML警告、渲染层报错、废弃API提示等底层日志)。 cdp action 需先以 cdp_enabled=true 打开项目，确保端口 9222 可用。 返回 JSON: {success, data: {logs, summary}, message}。

輸入參數params必填

wechat_screenshot

捕获界面截图

实时捕获当前小程序模拟器的界面截图。 默认支持截取长图，自动滚动并拼接。 output_path 可选，留空则自动保存到项目目录下 screenshots/ 文件夹。 返回 JSON: {success, data: {path, width, height, segments}, message}。

輸入參數params必填

wechat_navigate

跳转页面并采集 CDP 日志

跳转到指定页面，等待指定时间，通过 CDP 采集高清日志。 适用于页面生命周期日志检查（onLoad/onShow）、页面错误验证。 需先调用 wechat_automator(action='start') 并以 cdp_enabled=true 打开项目。 返回 JSON: {success, data: {current_page, cdp_logs}, message}。

輸入參數params必填

wechat_file

项目文件读取

读取小程序项目文件和结构信息。 支持 action: project_info(项目完整信息), list_pages(页面列表), read_page(读取页面源码), read_file(读取单个文件)。 返回 JSON: {success, data, message, error_code?}。

輸入參數params必填

版本歷史

2
  1. v0.9.20最新Oct 26, 2026
  2. v0.9.18Sep 16, 2026

評分

已滿足適用檢查項的 90%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分
  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分