VS Code 安装微信小程序 MCP 介绍

日期：2026-08-29

适用范围：Windows / VS Code / 微信开发者工具

一、什么是 MCP

MCP（Model Context Protocol，模型上下文协议） 是 Anthropic 提出的一套开放协议，让 AI 助手（如 VS Code 里的 Copilot、Claude 等）能够通过标准化的方式调用外部工具、读写数据。

简单说：MCP 相当于给 AI 装上了"手"。没有 MCP 时，AI 只能读代码、给建议；接入微信小程序 MCP 后，AI 可以直接：

启动/编译小程序
在模拟器中跳转页面
读取页面数据与元素
模拟点击、输入、滑动
截图、读取运行日志
断言页面状态（配合自动化测试）

二、什么是微信小程序 MCP

wechat-devtools-mcp 是一个社区开源项目 （GitHub: FliPPeDround/wechat-devtools-mcp，MIT 协议，TypeScript 编写，当前版本 0.0.1），它把「微信开发者工具」的 CLI 能力封装成 MCP 服务，让 AI 助手（Claude、Cursor、VS Code Copilot 等）能够直接操作微信开发者工具。

注意：该包由社区作者 FliPPeDround 开发维护，并非微信官方发布，但底层调用的是微信开发者工具官方提供的 CLI。

官方给出的功能特点：

通过 MCP 协议与 AI 代理（如 Claude、Cursor）集成
支持启动微信开发者工具并连接小程序项目
提供页面导航、元素操作、获取页面信息等自动化能力
支持控制台日志和异常监听

工作原理（一句话版）：

复制代码

AI 助手 ──MCP(stdio)──> wechat-devtools-mcp ──CLI/WebSocket(9420)──> 微信开发者工具

它依赖两样东西：

依赖	说明
微信开发者工具	需安装，且带 `cli.bat`（命令行入口）
小程序编译产物	指向编译后的 `mp-weixin` 目录（uni-app 项目）或小程序源码目录

本机实际配置中，--projectPath 指向的是 uni-app 编译产物：

wdmgwxcx/wdmgwxcxapp/unpackage/dist/dev/mp-weixin

三、前置条件

安装前请确认以下环境就绪：

项	要求	本机实测
VS Code	支持 MCP 的较新版本	✅
Node.js / npx	有 `npx` 命令	✅ npx 11.13.0
微信开发者工具	已安装（含 `cli.bat`）	✅ `D:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat`
小程序编译产物	已生成 `mp-weixin` 目录	✅ uni-app 先跑一次编译

注意：如果是 uni-app 项目，必须先执行编译（HBuilderX 或 CLI npm run dev:mp-weixin），生成 unpackage/dist/dev/mp-weixin 后，MCP 才有可操作的目标。

四、安装与配置步骤

4.1 安装微信开发者工具

到微信官方下载并安装微信开发者工具（稳定版即可），记下安装目录，确认存在 cli.bat：

复制代码

D:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat

4.2 在项目里创建 MCP 配置文件

在项目根目录的 .vscode 文件夹下创建 mcp.json（本机 wdmgwxcx 项目已有）：

json 复制代码

{
  "servers": {
    "wechat-devtools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "wechat-devtools-mcp",
        "--projectPath=e:/work/wdmgit/wdmgwxcx/wdmgwxcxapp/unpackage/dist/dev/mp-weixin",
        "--cliPath=D:/Program Files (x86)/Tencent/微信web开发者工具/cli.bat"
      ]
    }
  }
}

4.3 让 VS Code 生效

保存 mcp.json 后，VS Code 通常会自动识别工作区里的 MCP server（首次可能提示"是否信任/启动"）。
如未自动加载，可通过命令面板（Ctrl+Shift+P）执行 MCP: List Servers 查看是否出现 wechat-devtools。
确认 server 状态为 Running / Connected。

4.4 命令行手动验证（可选）

可先在终端里单独跑一次，确认包能启动：

powershell 复制代码

npx -y wechat-devtools-mcp --projectPath=e:/work/wdmgit/wdmgwxcx/wdmgwxcxapp/unpackage/dist/dev/mp-weixin --cliPath="D:/Program Files (x86)/Tencent/微信web开发者工具/cli.bat"

能启动且不报错，说明参数正确。

五、配置字段说明

5.1 MCP 配置字段（VS Code）

字段	值	说明
`type`	`stdio`	通信方式，标准输入输出（本包只支持 stdio）
`command`	`npx`	通过 npx 运行 npm 包（无需手动 `npm i -g`）
`-y`	自动确认	npx 在包不存在时自动下载，不询问

5.2 命令行参数（官方完整列表）

参数	类型	必填	说明
`--projectPath`	string	✅	小程序项目路径（uni-app 填 `unpackage/dist/dev/mp-weixin`）
`--cliPath`	string	否	微信开发者工具 CLI 路径（如 `cli.bat`；不填则用默认安装路径）
`--timeout`	number	否	连接超时时间（毫秒），默认 `30000`
`--port`	number	否	WebSocket 端口号，默认 `9420`
`--account`	string	否	用户 openid
`--ticket`	string	否	开发者工具登录票据
`--projectConfig`	string	否	覆盖 `project.config.json` 中的配置

5.3 ⚠️ 配置格式差异（最容易踩的坑）

不同客户端的 MCP 配置键名不同，千万别照抄错：

客户端	键名	配置文件位置
VS Code	`"servers"`	项目 `.vscode/mcp.json`
Claude Desktop / Cursor	`"mcpServers"`	`claude_desktop_config.json` / Cursor 设置

官方 README 给的示例用的是 mcpServers（Claude/Cursor 格式）；VS Code 里必须用 servers，否则识别不到。

路径要点：

必须用绝对路径；

Windows 路径建议用 /（正斜杠），避免 JSON 转义问题；

--cliPath 含中文和空格，JSON 里直接写即可，但终端手动测试时要加引号；

首次运行 npx 会自动下载包（需联网），可先 npm config set registry https://registry.npmmirror.com 加速。

六、接入后 AI 能做什么（工具能力清单）

本机接入 wechat-devtools 后，暴露的工具大致如下：

分类	工具	用途
启动	`launch`	启动/打开小程序
页面跳转	`navigateTo` / `redirectTo` / `reLaunch` / `switchTab` / `navigateBack`	模拟页面流转
页面状态	`currentPage` / `pageStack` / `getPageSize`	当前页、页面栈、页面尺寸
数据	`getPageData` / `setPageData`	读取/修改页面 data
日志	`getlogs` / `getexceptions`	读取 console 日志与异常
元素	`getElement` / `getElements` / `getElementWxml` / `getElementText` / `getElementValue` / `getElementData` / `getElementAttribute` / `getElementStyle` 等	查询元素结构、文本、值、属性
交互	`tapElement` / `inputElement` / `longpressElement` / `touchstart` / `touchmove` / `touchend` / `triggerElement`	模拟点击、输入、手势
滚动	`scrollTo` / `swipeTo` / `moveTo` / `getScrollTop`	滚动与滑动
截图	`screenshot`	截图（AI 可"看到"界面）
系统	`systemInfo`	设备/系统信息
登录	`getTicket` / `testAccounts`	获取登录凭证、测试账号
Mock	`mockWxMethod` / `restoreWxMethod`	模拟 wx API 返回值
其他	`waitFor` / `exposeFunction` / `callWxMethod` / `callContextMethod` 等	等待条件、调用方法

七、典型使用场景

一句话让 AI 帮你启动并查看小程序 ：AI 调用 launch + screenshot，直接"看到"界面。
页面流转验证 ：AI 依次 navigateTo → currentPage → pageStack，核对跳转是否正确。
Bug 定位 ：AI 读 getlogs / getexceptions，结合截图定位报错页面与元素。
数据断言 ：AI 读 getPageData 检查渲染数据是否符合预期。
自动化回归：AI 模拟点击、输入、滚动，完成一条业务流（如登录→加购→下单）的冒烟测试。
Mock 接口 ：AI 用 mockWxMethod 模拟 wx.login 等返回值，隔离后端做前端测试。

八、常见问题（FAQ）

Q1：VS Code 里 MCP 没出现？

确认 .vscode/mcp.json 路径与 JSON 格式正确；命令面板执行 MCP: List Servers；重启 VS Code 试试。

Q2：报"找不到 cli.bat"？

检查微信开发者工具是否安装、--cliPath 是否写对完整路径（含 cli.bat）。

Q3：报"项目路径不存在"？

uni-app 项目先编译一次，生成 unpackage/dist/dev/mp-weixin；确认 --projectPath 指向该目录。

Q4：中文路径乱码？

配置时路径建议用正斜杠 D:/Program Files (x86)/Tencent/微信web开发者工具/cli.bat，不要用反斜杠转义。

Q5：npx 下载包很慢？

首次会自动下载 wechat-devtools-mcp，可用 npm config set registry https://registry.npmmirror.com 切换镜像。

Q6：配置写对了但 VS Code 不认？

检查键名是 servers 而不是 mcpServers（后者是 Claude/Cursor 的格式）。

Q7：报端口 9420 被占用 / 连接超时？

用 --port 换一个端口，或调大 --timeout（默认 30000 毫秒）。

Q8：AI 能连上但看不到小程序界面？

确认微信开发者工具已用该 CLI 打开过项目；确认 --projectPath 是编译产物目录，而非 uni-app 源码根目录。

Q9：这个包是微信官方的吗？

不是。wechat-devtools-mcp 是社区开源项目（MIT，作者 FliPPeDround），底层调用微信开发者工具官方 CLI。生产使用前建议关注其仓库（GitHub: FliPPeDround/wechat-devtools-mcp）的活跃度与维护情况。

九、小结

步骤	内容
1	安装微信开发者工具（确认 `cli.bat`）
2	生成小程序编译产物（uni-app 需先编译）
3	项目 `.vscode/mcp.json` 写入 `wechat-devtools` 配置
4	VS Code 识别并启动 MCP server
5	在对话中让 AI 直接操作小程序（启动、跳转、截图、读日志、模拟点击）

接入微信小程序 MCP 后，AI 从"只能看代码"升级为"能真实操作小程序"，非常适合页面联调、Bug 复现、自动化冒烟测试等场景。