Skip to main content
Glama

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、调用 wx API、原生弹窗操作。

不使用改包、注入或私有协议。实现只依赖官方 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 start

MCP 走 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)

环境变量

变量

作用

默认

WECHAT_DEVTOOLS_DIR

开发者工具安装目录

C:\Program Files (x86)\Tencent\微信web开发者工具

WECHAT_DEVTOOLS_PROJECT

默认小程序项目目录

空

WECHAT_DEVTOOLS_AUTOMATION_PORT

自动化端口

9420

WECHAT_DEVTOOLS_MCP_OUTPUT_DIR

截图输出目录

<repo>/output

WECHAT_DEVTOOLS_MCP_ALLOW_UPLOAD

设为 1 才允许上传工具

未设置

WECHAT_DEVTOOLS_SKIP_SERVICE_PORT_CHECK

设为 1 跳过预检查

未设置

WECHAT_DEVTOOLS_NO_STALE_CLEANUP

设为 1 禁止清理退出后残留的 .ide 端口文件

未设置

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:调用 wx API。

  • 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:e2e

License

MIT

Available Tools

23 tools
wdt_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关闭项目窗口A
Destructive

关闭指定项目窗口,不退出整个开发者工具。

Inputs: projectPath.

wdt_current_page获取当前页面与页面栈B
Read-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检查开发者工具登录状态A
Read-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_navigate页面跳转C

在当前小程序中跳转:navigateTo / redirectTo / reLaunch / switchTab / navigateBack。

Inputs: mode (required), url, validate.

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查询页面元素B
Read-only

用 CSS 选择器查询当前页面元素,返回 tagName、文本、id/class、value 等摘要。

Inputs: selector (required), all, max.

wdt_quit退出开发者工具A
Destructive

退出整个微信开发者工具。会关闭所有项目窗口。

Inputs: no named parameters.

wdt_screenshot截取模拟器画面A
Read-only

截取当前小程序模拟器画面为 PNG。path 省略时写入 MCP output 目录并返回文件路径。

Inputs: path.

wdt_status微信开发者工具环境状态A
Read-only

检查开发者工具路径、服务端口开关、自动化连接状态与端口占用。开始任何操作前可先调用。

Inputs: no named parameters.

wdt_system_info获取小程序系统信息C
Read-only

返回 miniProgram.systemInfo()。

Inputs: no named parameters.

wdt_upload上传小程序版本(默认禁用)A
Destructive

调用官方 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

    A3.5/5.0

    Scored across 23 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to automate WeChat mini-programs via launch or connect modes, providing a stable interaction tree for observation and operation.
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      Wraps 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.
      7
      167
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      61
      1
      MIT