微信小程序 MCP 服务器

微信小程序 MCP 服务器（weapp-dev-mcp）#

资源概述#

weapp-dev-mcp 是一个基于 FastMCP 的 MCP（Model Context Protocol）服务器，通过 miniprogram-automator 自动化微信开发者工具。它让 AI 助手（Claude Desktop、Claude Code、Cursor 等）能够像 Playwright 操作浏览器一样，直接导航、检查、截图和操作小程序页面。

核心价值：

AI 原生：专为 AI 助手设计，提供 20+ 个细粒度 MCP 工具
自动化测试：页面截图、元素定位、数据读写、控制台日志采集
Agentic 工作流：AI 可以自主导航小程序、验证 UI、调试问题
Claude/Cursor 集成：标准 MCP 协议，一键接入主流 AI 开发工具

典型场景：

AI 辅助的小程序 UI 回归测试
自动化截图对比与视觉验证
AI 助手读取页面 data、调用页面方法进行调试
控制台日志采集供 AI 分析错误

设计规范#

架构模型#

MCP 服务器：基于 FastMCP 实现，提供标准 MCP 协议接口
底层引擎：miniprogram-automator（微信官方自动化 SDK）
连接方式：WebSocket（ws://localhost:9420）或 CLI 自动启动
环境变量：WEAPP_WS_ENDPOINT（推荐）、WECHAT_DEVTOOLS_CLI_PATH、WEAPP_AUTOMATOR_MODE

工具分类#

类别	工具前缀	功能
小程序级	`mp_`	连接管理、导航、截图、日志、项目列表
页面级	`page_`	元素查询、data 读写、方法调用、等待
元素级	`element_`	点击、输入、属性、样式、WXML、滚动

元素定位策略#

CSS 选择器：page_getElement('.class-name')
XPath：page_getElementByXpath('//view[@id="test"]')
等待策略：page_waitElement('.dynamic-element', { timeout: 5000 })

审核规范#

N/A（开源工具项目，不涉及小程序审核）。但使用此工具需要：

微信开发者工具开启服务端口
开启HTTP 调试和自动化测试（设置 → 安全设置）
本地项目需有有效 AppID

开发指南#

快速上手#

code

# 方式 1：npx 直接运行
npx -y @yfme/weapp-dev-mcp

# 方式 2：全局安装
npm install -g @yfme/weapp-dev-mcp
weapp-dev-mcp

# 方式 3：项目依赖
npm install --save-dev @yfme/weapp-dev-mcp
npx weapp-dev-mcp

启动微信开发者工具（自动化模式）#

code

# macOS
/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

MCP 客户端配置#

code

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

Claude Code 权限自动批准#

code

{
  "permissions": {
    "allow": [
      "mcp__weapp-dev-mcp__mp_ensureConnection",
      "mcp__weapp-dev-mcp__mp_navigate",
      "mcp__weapp-dev-mcp__mp_screenshot",
      "mcp__weapp-dev-mcp__mp_callWx",
      "mcp__weapp-dev-mcp__mp_getLogs",
      "mcp__weapp-dev-mcp__page_getElement",
      "mcp__weapp-dev-mcp__page_getElements",
      "mcp__weapp-dev-mcp__element_tap",
      "mcp__weapp-dev-mcp__element_input"
    ]
  }
}

常见陷阱#

连接丢失：MCP 与 DevTools 的 WebSocket 连接可能在工具权限确认时断开，建议预先配置 allow 列表
端口冲突：默认端口 9420，如被占用可通过 --auto-port 指定其他端口
安全设置：必须在 DevTools 中开启服务端口 + HTTP 调试 + 自动化测试，否则 CLI 无法连接
沙箱限制：部分 MCP 客户端沙箱不允许访问项目目录外的 CLI，推荐用 WebSocket 连接模式
Node 版本：需要 Node.js 18+

生态资源#

项目	关系	说明
miniprogram-automator	底层依赖	微信官方自动化 SDK
FastMCP	协议框架	MCP 服务器实现框架
playwright-mcp	类似工具	浏览器自动化 MCP（类比参考）
ai-mode-skills	互补工具	微信官方 AI 开发模式 Skills

MCP 生态#

MCP 协议规范：modelcontextprotocol.io
Claude Desktop MCP 配置文档
Cursor MCP 集成

版本更新#

当前版本：v0.2.5（npm）#

近期重要变更#

v0.2.5：稳定性修复，增强自动启动和连接管理
MCP 工具集：20+ 个工具覆盖小程序级、页面级、元素级操作
npm 包发布：@yfme/weapp-dev-mcp 正式发布到 npm
多客户端支持：Claude Desktop、Claude Code、Cursor、Codex 等
GitHub 167 stars（2026-07-19）：社区活跃度持续增长

微信小程序 MCP 服务器

详细文档

微信小程序 MCP 服务器（weapp-dev-mcp）#

资源概述#

设计规范#

架构模型#

工具分类#

元素定位策略#

审核规范#

开发指南#

快速上手#

启动微信开发者工具（自动化模式）#

MCP 客户端配置#

Claude Code 权限自动批准#

常见陷阱#

生态资源#

相关项目#

MCP 生态#

版本更新#

当前版本：v0.2.5（npm）#

近期重要变更#