weapp-dev-mcp

🚀 微信小程序 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 在启动阶段抛出 “Server does not support completions” 错误。
• 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 对象覆盖这些默认值中的大部分。

常见错误

• Server does not support completions (required for completion/complete)
  新版 @modelcontextprotocol/sdk 在启动阶段强制要求 completions 能力，而当前版本的 weapp-dev-mcp 尚未实现相关接口。按照“快速开始”章节的命令显式安装 @modelcontextprotocol/sdk@1.17.2 与 fastmcp@3.23.0 可立即规避；未来版本将内置兼容逻辑。

💻 可用工具

应用工具（Application Tools）

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

页面工具（Page Tools）

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

元素工具（Element Tools）

• 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）来定位自定义组件。

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

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

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

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

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

方法二：使用元素内查询工具

适用于 element_getInnerElement 和 element_getInnerElements：

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

限制说明

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