WeChat DevTools MCP
Enables AI agents to drive WeChat DevTools on Windows, including opening/closing projects, login, preview generation, npm build, guarded upload, and simulator control such as page navigation, element querying/clicking/input, screenshots, evaluate, wx API calls, and native dialog actions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@WeChat DevTools MCP open my mini program project and screenshot the simulator"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
WeChat DevTools MCP
Local MCP server that lets an AI agent drive WeChat DevTools on Windows: the official CLI for project operations, and the official mini program automation SDK for simulator control.
把微信开发者工具接到 AI 的本地 MCP 服务。控制面分两层:
官方 CLI:打开项目、关闭项目、退出 IDE、登录、预览、构建 npm、上传(默认禁用)。
官方自动化 SDK:连接模拟器,做页面跳转、元素查询/点击/输入、截图、
evaluate、调用wxAPI、原生弹窗操作。
不使用改包、注入或私有协议。实现只依赖官方 CLI、miniprogram-automator 和本地进程管理。
环境要求
Windows,已安装微信开发者工具。默认路径:
C:\Program Files (x86)\Tencent\微信web开发者工具Node.js >= 20。
开发者工具里开启 设置 → 安全设置 → 服务端口(CLI/HTTP 调用)。自动化必需。
预览、上传需要开发者工具已登录。
touristappid只能用于本地模拟器自动化;CLI 的 open/build-npm/preview 需要真实 AppID。
Related MCP server: miniprogram-automator-mcp
安装
git clone https://github.com/sdjvhbuw/wechat-devtools-mcp.git
cd wechat-devtools-mcp
npm install
npm startMCP 走 stdio,日志只写 stderr,不会污染协议输出。
项目结构
src/runtime.js 路径、CLI 调用、IDE 端口检测、残留状态清理
src/session.js 自动化连接生命周期、复用/重启、页面轮询
src/server.js MCP 工具注册与参数校验
scripts/e2e.js 模拟器自动化回归
scripts/cli-e2e.js open/close/preview/quit/恢复回归
scripts/smoke.js 最小联调脚本
test-fixtures/ 测试用小程序(touristappid)环境变量
变量 | 作用 | 默认 |
| 开发者工具安装目录 |
|
| 默认小程序项目目录 | 空 |
| 自动化端口 |
|
| 截图输出目录 |
|
| 设为 | 未设置 |
| 设为 | 未设置 |
| 设为 | 未设置 |
CLI 需要 token 时用 WECHAT_DEVTOOLS_CLI_TOKEN(不通过工具参数传递)。
接入 MCP 客户端
Qoder、Claude Desktop、Cursor、Codex 等客户端都使用同样的 stdio 配置。把路径换成仓库的实际绝对路径:
{
"mcpServers": {
"wechat-devtools": {
"command": "node",
"args": ["C:/path/to/wechat-devtools-mcp/src/server.js"],
"env": {
"WECHAT_DEVTOOLS_PROJECT": "C:/path/to/your-miniprogram",
"WECHAT_DEVTOOLS_AUTOMATION_PORT": "9420"
}
}
}
}Qoder 写在 ~/.qoder/settings.json,其他客户端按各自文档放到对应位置。修改后重启客户端或重载 MCP。
启动与退出恢复
调用 open / login / preview / build-npm / auto_start 前,先确保 IDE 以正常 GUI 方式启动,再交给 CLI,避免 CLI 冷启动时抢在服务端口就绪之前检查。
开发者工具退出后可能残留
Default/.ide和.ide-status=On,导致 CLI 一直等待旧端口。检测到端口已关闭且文件超过 15 秒未更新时,会备份为.ide.stale-<时间>并清理,同时把状态写为Off。wdt_quit会等待实际.ide端口关闭(最多 40 秒),然后清理残留。不想让 MCP 动这些状态文件时设
WECHAT_DEVTOOLS_NO_STALE_CLEANUP=1。手动改过安全设置后,可先用
wdt_status看ide.portOpen、servicePort.configured和servicePort.ok(ok表示配置已开启且 IDE 端口当前真的在线)。
工具
环境与 CLI
wdt_status:工具路径、服务端口开关、自动化连接、端口占用。wdt_open/wdt_close_project/wdt_quit:打开、关闭项目、退出 IDE。wdt_quit会等待 IDE 端口关闭(最多 40 秒)。wdt_login/wdt_is_login:触发扫码登录 / 检查登录状态。wdt_preview:生成预览二维码(terminal/image/base64)。image/base64 未给路径时自动写入 output。wdt_build_npm:构建 npm;失败时返回ok=false和可读hint。wdt_upload:上传版本。默认禁用,需环境变量 +confirm=true。
自动化
wdt_auto_start:启动并连接自动化端口。默认复用已有连接;restart=true强制重启。总预算默认 45 秒。wdt_auto_connect/wdt_disconnect:连接已有端口 / 断开。wdt_current_page:当前页面与页面栈。wdt_navigate:navigateTo / redirectTo / reLaunch / switchTab / navigateBack;默认按app.json校验页面,动态页面可传validate=false。wdt_query:按 CSS 选择器查询元素摘要。wdt_element:tap、input、text、attribute、wxml、trigger、scrollTo、scrollWidth/Height、swipeTo、slideTo、callMethod 等动作。slideTo会补发 change 事件。wdt_wait:等待选择器或毫秒数(最长 60 秒)。wdt_page_data:读取/修改页面 data,或调用页面方法(SDK 调用失败时自动用 evaluate 回退)。wdt_screenshot:模拟器截图,返回 PNG 路径。wdt_evaluate:执行表达式/语句/函数;表达式自动包成函数,可用$args访问参数。wdt_wx_method:调用wxAPI。wdt_native:goHome、确认/取消弹窗、授权、分享等原生动作。wdt_system_info:systemInfo()。
联调
node scripts/smoke.js "C:/path/to/your-miniprogram"脚本会依次执行:状态检查 → 启动自动化 → 当前页面 → 查询 view → 截图 → 断开。任何一步失败都会返回 CLI 输出,便于定位服务端口或登录问题。
回归测试:
npm run test:e2e # 55 项:输入/点击/滑动/滚动/跳转/求值/错误路径
npm run test:cli # open/close/preview/build/quit/恢复test:cli 会退出并重新拉起 IDE,运行前保存好未提交的工作。open/preview 需要真实 AppID,用环境变量提供你自己的小程序项目;未提供时相关用例标记为 SKIP:
# PowerShell
$env:WECHAT_DEVTOOLS_TEST_USER_PROJECT="C:/path/to/your-miniprogram"
npm run test:cli测试用小程序在 test-fixtures/miniprogram,只用于模拟器自动化。
安全边界
wdt_upload默认不可用,避免 AI 误发布;需要显式设置环境变量并传confirm=true。wdt_quit、wdt_close_project、wdt_upload标记为 destructive;调用前应确认。wdt_evaluate和wdt_wx_method属于本地任意执行能力,只在可信项目中使用。MCP 只监听 stdio,不开放网络端口;请不要把
wdt_evaluate暴露给不可信输入。本项目只操作微信开发者工具及其模拟器,不控制微信客户端本身。
miniprogram-automator的jimp/phin链仍有 5 个 moderate 上游告警;critical/high 已通过 npm overrides 处理。详见 SECURITY.md。
已知限制
仅支持 Windows。
只覆盖“项目 + 模拟器”两层;IDE 自身的菜单、设置面板等界面级操作未实现。
wdt_preview/wdt_upload需要开发者工具已登录;touristappid不能用于 CLI 的 open/build/preview。微信开发者工具升级后,CLI 参数或自动化协议可能变化;请先跑
npm run test:e2e。
版本管理
版本号遵循 SemVer,变更记录见 CHANGELOG.md。发布前建议:
npm run check
npm run format:check
npm run test:e2eLicense
Available Tools
23 toolswdt_auto_connect连接已开启的自动化端口B
不启动 IDE,直接连接一个已经用 auto 模式打开的自动化端口。
Inputs: timeoutMs, wsEndpoint.
wdt_auto_start启动自动化并连接模拟器A
通过 CLI auto 打开项目并开启自动化端口,然后建立 WebSocket 连接。需要服务端口开启。后续 wdt_current_page / wdt_query / wdt_element / wdt_screenshot 等工具依赖此连接。
Inputs: port, restart, timeoutMs, projectPath.
wdt_build_npm构建小程序 npmC
调用官方 CLI 执行 build-npm,构建项目依赖。
Inputs: projectPath.
wdt_close_project关闭项目窗口ADestructive
关闭指定项目窗口,不退出整个开发者工具。
Inputs: projectPath.
wdt_current_page获取当前页面与页面栈BRead-only
返回当前小程序页面的路径、query,以及页面栈路径。
Inputs: no named parameters.
wdt_disconnect断开自动化连接A
关闭 WebSocket 自动化连接;closeProject=true 时同时关闭项目窗口。不会退出开发者工具。
Inputs: closeProject.
wdt_element操作或读取页面元素C
对匹配 selector 的第 index 个元素执行动作:tap/longpress/input/text/value/attribute/property/style/wxml/outerWxml/size/offset/trigger/scrollTo/scrollWidth/scrollHeight/swipeTo/slideTo/callMethod/callContextMethod/setData/data。slideTo 会补发 change 事件;swipeTo 只改视觉索引。
Inputs: action (required), selector (required), x, y, +9 more.
wdt_evaluate在小程序 App 上下文执行表达式A
在 miniProgram.evaluate 中执行表达式或函数体,返回可序列化结果。默认把输入当表达式自动包成函数;mode=function 时原样传入函数声明。可通过 $args 访问 args 参数。仅用于本地调试,注意副作用。
Inputs: expression (required), args, mode.
wdt_is_login检查开发者工具登录状态ARead-only
调用官方 CLI islogin,返回当前是否已登录。预览和上传前建议先检查。
Inputs: no named parameters.
wdt_login登录开发者工具A
触发官方 CLI 登录,stdout 中通常包含二维码(终端字符画)。需要用户用微信扫码。
Inputs: no named parameters.
wdt_native模拟器原生交互C
执行原生层动作:goHome / navigateLeft / confirmModal / cancelModal / authorizeAllow / authorizeCancel / closePaymentDialog / shareCancel / shareConfirm / switchTab。
Inputs: action (required), url.
wdt_open在开发者工具中打开项目A
调用官方 CLI 打开(或聚焦)一个小程序项目。需要服务端口开启;登录状态由 IDE 决定。
Inputs: port, projectPath.
wdt_page_data读取/修改页面数据或调用页面方法C
action=get 读取 data(可选 path);action=set 调用 setData;action=call 调用页面方法。
Inputs: action (required), args, data, path, +1 more.
wdt_preview生成小程序预览二维码B
调用官方 CLI 生成预览。qrFormat=image/base64 时可把二维码写入 qrOutput。需要已登录。
Inputs: qrFormat, qrOutput, infoOutput, projectPath.
wdt_query查询页面元素BRead-only
用 CSS 选择器查询当前页面元素,返回 tagName、文本、id/class、value 等摘要。
Inputs: selector (required), all, max.
wdt_quit退出开发者工具ADestructive
退出整个微信开发者工具。会关闭所有项目窗口。
Inputs: no named parameters.
wdt_screenshot截取模拟器画面ARead-only
截取当前小程序模拟器画面为 PNG。path 省略时写入 MCP output 目录并返回文件路径。
Inputs: path.
wdt_status微信开发者工具环境状态ARead-only
检查开发者工具路径、服务端口开关、自动化连接状态与端口占用。开始任何操作前可先调用。
Inputs: no named parameters.
wdt_system_info获取小程序系统信息CRead-only
返回 miniProgram.systemInfo()。
Inputs: no named parameters.
wdt_upload上传小程序版本(默认禁用)ADestructive
调用官方 CLI 上传版本到微信后台。默认禁用;仅在 WECHAT_DEVTOOLS_MCP_ALLOW_UPLOAD=1 且 confirm=true 时执行。此操作会发布版本,不可撤销。
Inputs: desc (required), version (required), confirm, projectPath.
wdt_wait等待页面条件A
等待 CSS 选择器出现(传字符串)或等待固定毫秒数(传数字),最长 60 秒。
Inputs: target (required), timeoutMs.
wdt_wx_method调用 wx APIC
通过 miniProgram.callWxMethod 调用 wx 方法,并返回结果。例如 getSystemInfoSync、getStorageSync。
Inputs: method (required), args.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Most tools have clearly distinct purposes (build, login, preview, upload, navigate, screenshot, etc.), and the descriptions disambiguate overlapping pairs like wdt_open vs wdt_auto_start vs wdt_auto_connect and wdt_close_project vs wdt_quit vs wdt_disconnect. The remaining fuzziness is in the runtime-evaluation cluster: wdt_evaluate, wdt_wx_method, and wdt_page_data all execute things inside the mini program, and wdt_element is a mega-tool with ~20 actions that could be mistaken for wdt_page_data or wdt_native depending on the task.
Every tool uses the same wdt_ prefix with snake_case descriptive names (wdt_build_npm, wdt_current_page, wdt_system_info), with no camelCase or style drift. The verb/noun ordering is predictable and readable throughout.
23 tools is on the high side, but the surface splits into two real layers (official CLI control and automation-socket interaction), and nearly every tool maps to a distinct operation with no obvious filler. It is slightly heavy — a few tools like wdt_auto_connect/wdt_disconnect could be folded in — but not bloated.
Coverage of the domain is strong: project lifecycle, login/preview/upload, automation connect/disconnect, page navigation, element interaction, data access, screenshots, wx method calls, and waiting are all present. Notable gaps are console/log retrieval and network request interception/mocking, plus richer storage or performance tooling, which agents would need workarounds for.
Maintenance
Related MCP Connectors
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Let your AI agent control real iPhones: screenshots, tap, swipe, type and open apps.
A paid remote MCP for AI agent browser DevTools MCP, built to return verdicts, receipts, usage logs,
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables AI assistants to automate WeChat Developer Tools for mini programs, allowing navigation, inspection, and manipulation of pages and components through the miniprogram-automator API.27136 npm174MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to automate WeChat mini-programs via launch or connect modes, providing a stable interaction tree for observation and operation.MIT
- AlicenseAqualityAmaintenanceWraps the WeChat DevTools CLI as an MCP service, enabling AI in editors to call WeChat CLI commands for mini-program development, testing, debugging, and automation.7167MIT
- AlicenseBqualityCmaintenanceEnables AI assistants to control WeChat mini-programs running in WeChat Developer Tools through MCP tools. Provides automation capabilities for launching, navigating, querying, and interacting with pages and elements.611MIT