微信小程序MCP服务器

基于FastMCP服务器，通过miniprogram-automator自动化微信开发者工具。该服务器提供MCP工具，允许AI助手导航、检查和操作小程序页面——类似于playwright-mcp，但特别针对微信生态系统进行了定制。

预备条件

• 已安装微信开发者工具，支持命令行访问（cli / cli.bat）
• 本地安装Node.js 18+ 和 npm
• 可以在开发者工具中打开的小程序项目

快速开始（npm包）

@yfme/weapp-dev-mcp已发布到npm，普通用户无需克隆仓库或手动执行 node dist/index.js。以下命令将直接从npm下载可执行版本。

使用NPX临时运行（推荐）

npx -y \
  -p @modelcontextprotocol/sdk@1.17.2 \
  -p fastmcp@3.23.0 \
  -p @yfme/weapp-dev-mcp \
  weapp-dev-mcp

• -y 自动确认依赖安装。
• 通过 -p 明确锁定 @modelcontextprotocol/sdk@1.17.2 和 fastmcp@3.23.0，可以避免新SDK在启动阶段抛出的“服务器不支持完整性”错误。
• weapp-dev-mcp 是从包导出的CLI名称。

安装到项目/全局

npm install --save-dev \
  @modelcontextprotocol/sdk@1.17.2 \
  fastmcp@3.23.0 \
  @yfme/weapp-dev-mcp

npx weapp-dev-mcp

或者使用 npm install -g ... && weapp-dev-mcp，SDK和fastmcp版本也需要锁定。

建议仅在本仓库内开发时直接运行 node dist/index.js。对于一般用户，请使用上述npm包方法开始。

MCP客户端集成

配置

要在Claude Desktop或其他MCP客户端中使用此服务器，请添加：

{
  "mcpServers": {
    "weapp-dev": {
      "command": "npx",
      "args": [
        "-y",
        "-p", "@modelcontextprotocol/sdk@1.17.2",
        "-p", "fastmcp@3.23.0",
        "-p", "@yfme/weapp-dev-mcp",
        "weapp-dev-mcp"
      ],
      "env": {
        "WEAPP_WS_ENDPOINT": "ws://localhost:9420"
      }
    }
  }
}

启动微信开发者工具

在使用MCP服务器之前，需要启动微信开发者工具并启用WebSocket服务。

💡 启动前：

1. 打开微信开发者工具
2. 进入 设置 → 安全设置 → 服务端口
3. 开启 HTTP调试 和 自动化测试

使用命令行启动

从命令行启动微信开发者工具，并自动启用WebSocket服务：

macOS/Linux：

/Applications/wechatwebdevtools.app/Contents/MacOS/cli auto --project /path/to/your/project --auto-port 9420

Windows：

"C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat" auto --project C:\path\to\your\project --auto-port  9420

其中

• --project 参数指定小程序项目的目录路径（请替换为实际项目路径）
• --auto-port 参数指定WebSocket服务端口（默认9420）

⚠️ 警告 由于沙箱机制，某些客户端不允许MCP访问项目目录外的微信开发者工具CLI，因此这里只介绍如何使用WebSocket服务

环境变量配置

如何通过环境变量控制将自动化工具连接到微信开发者工具：

变量	描述
WEAPP_WS_ENDPOINT	【推荐】 实现开发者工具WebSocket端点。设置后，服务器使用 connect 模式而不是启动新实例。示例：ws://localhost:9420
WECHAT_DEVTOOLS_CLI_PATH	微信开发者工具CLI路径（如果默认路径有效则可选）。
WEAPP_AUTOMATOR_MODE	强制使用 launch 或 connect 模式。除非提供了 WEAPP_WS_ENDPOINT，否则默认为 launch。
WEAPP_DEVTOOLS_PORT	启动开发者工具时首选端口（回退到可用端口）。
WEAPP_DEVTOOLS_TIMEOUT	启动超时（毫秒，默认30000）。
WEAPP_AUTO_ACCOUNT	传递给 --auto-account 用于自动登录。
WEAPP_DEVTOOLS_TICKET	在启动时传递给 --ticket。
WEAPP_TRUST_PROJECT	设置为 true 以便在启动时包含 --trust-project。
WEAPP_DEVTOOLS_ARGS	启动时附加的CLI参数（空格分隔）。
WEAPP_DEVTOOLS_CWD	传递给开发者工具进程的工作目录。
WEAPP_AUTOCLOSE	设置为 true 在每次工具调用后关闭开发者工具会话。

注意： 启动开发者工具（launch模式时，必须通过MCP工具参数提供小程序项目目录：connection.projectPath 提供（例如通过）mp_ensureConnection）。一旦建立，此值将在后续调用中持久化。

工具调用可以通过 connection 对象覆盖大多数这些默认值。

常见错误

• 服务器不支持完整性（完成/完整所需）
  新版本 @modelcontextprotocol/sdk 在启动阶段需要强制完成能力，而当前版本 weapp-dev-mcp 相关接口尚未实现。根据“快速开始”部分中的命令明确安装 @modelcontextprotocol/sdk@1.17.2 和 fastmcp@3.23.0 可立即避免；未来版本将内置兼容逻辑。

可用工具

应用工具

• mp_ensureConnection - 确保自动化会话准备就绪；可以选择强制重新连接或覆盖连接设置
• mp_navigate - 小程序内的导航，支持 navigateTo、redirectTo、reLaunch、switchTab 或 navigateBack
• mp_screenshot - 捕获屏幕截图并返回（或保存到磁盘）
• mp_callWx - 调用微信小程序API方法（如 wx.showToast）
• mp_getLogs - 获取小程序控制台日志，可以选择在检索后清除

页面工具

• page_getElement - 通过选择器检索页面元素
• page_waitElement - 等待元素出现在页面上（⚠️ 不适用于自定义组件内部元素）
• page_waitTimeout - 等待指定的毫秒数
• page_getData - 检索当前页面的数据对象并指定路径
• page_setData - 使用 setData 更新当前页面的数据
• page_callMethod - 调用当前页面实例上暴露的方法

元素工具

• element_tap - 通过CSS选择器点击WXML元素
• element_input - 向元素输入文本（适用于 input 和 textarea 组件）
• element_callMethod - 调用自定义组件实例的方法（需要ID选择器）
• element_getData - 获取自定义组件实例的渲染数据（需要ID选择器）
• element_setData - 设置自定义组件实例的渲染数据（需要ID选择器）
• element_getInnerElement - 检索元素内的元素（相当于 element.$(selector)）
• element_getInnerElements - 检索元素内的元素数组（相当于 element.$$(selector)）
• element_getSize - 获取元素大小（宽度和高度）
• element_getWxml - 获取元素WXML（内部或外部）

每个工具接受可选选项 connection 块来覆盖默认环境值（项目路径、CLI路径、WebSocket端点等）。

使用提示

通用提示

• 在连接前启用微信开发者工具的自动化（设置 → 安全设置 → 服务端口）
• 推荐首先调用 mp_ensureConnection 来验证连接并查看系统/页面详情
• 使用 WEAPP_AUTOCLOSE=true 适合无状态的一次性交互
• 导航时始终使用绝对路径（以 / 开头）：/pages/mine/mine
• TabBar页面使用 switchTab，常规页面使用 navigateTo

操作自定义组件

🔴 重要：必须使用ID选择器（如 #my-component）定位自定义组件

操作自定义组件有两种方法：

方法1：使用 innerSelector 参数（推荐）

适用于 element_tap、element_input、element_getSize、element_getWxml 等工具：

{
  "selector": "#my-component",
  "innerSelector": ".inner-button"
}

• selector 自定义组件的ID选择器
• innerSelector：组件内部元素的选择器

方法2：使用元素查询工具

适用于 element_getInnerElement 和 element_getInnerElements：

{
  "selector": "#my-component",
  "targetSelector": ".inner-button"
}

限制说明

• page_waitElement 不适用于自定义组件内部元素。请使用 page_waitTimeout 结合元素查询工具进行轮询检查。
• 操作自定义组件（如 element_callMethod、element_getData、element_setData）需要组件具有 id 属性。