uniapp WeChat MCP

English | 中文

面向 uniapp 微信小程序的 Node.js MCP Server。它通过微信开发者工具官方 CLI 和 miniprogram-automator SDK，提供打开项目、编译、预览、截图、日志采集、页面跳转、元素点击、读取页面 data、读取源码文件等能力。

npm 包内同时包含 .agents/skills/wechat-devtools，AI 客户端可以读取这份 skill 来了解推荐工作流。

安装与运行

通常不需要全局安装，MCP 客户端直接用 npx 启动：

npx -y uniapp-wechat-mcp

要求：

• Node.js >=18.17
• 已安装微信开发者工具
• 微信开发者工具中已开启服务端口：设置 -> 安全设置 -> 服务端口 -> 开启

MCP 配置

只需要配置一个环境变量：WECHAT_DEVTOOLS_CLI，指向微信开发者工具官方 cli。

macOS 示例：

{
  "mcpServers": {
    "uniapp-wechat": {
      "command": "npx",
      "args": ["-y", "uniapp-wechat-mcp"],
      "env": {
        "WECHAT_DEVTOOLS_CLI": "/Applications/wechatwebdevtools.app/Contents/MacOS/cli"
      }
    }
  }
}

Windows 示例：

{
  "mcpServers": {
    "uniapp-wechat": {
      "command": "npx",
      "args": ["-y", "uniapp-wechat-mcp"],
      "env": {
        "WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat"
      }
    }
  }
}

如果你的微信开发者工具安装路径不同，请把 WECHAT_DEVTOOLS_CLI 改成自己的实际路径。

可选环境变量

wechat_ide(action="status") 会自动读取微信开发者工具的设置文件以确认服务端口和登录状态。默认按平台自动发现：

• macOS：~/Library/Application Support/微信开发者工具/<hash>/WeappLocalData/ls_*.json
• Windows：%APPDATA%/微信开发者工具/User Data/<hash>/WeappLocalData/ls_*.json

如果发现不到，可以手动覆盖：

• WECHAT_DEVTOOLS_USER_DATA：用户数据根目录
• WECHAT_DEVTOOLS_SETTINGS：直接指向 ls_*.json 文件

项目路径规则

工具调用时可以不传 project_path。MCP 会优先从当前 workspace 自动发现小程序项目。

对 uniapp 项目，会自动查找：

unpackage/dist/dev/mp-weixin
unpackage/dist/build/mp-weixin

如果传入的是原生微信小程序目录，该目录需要包含：

project.config.json
app.json

推荐调用顺序

首次连接或新会话：

wechat_ide(action="status")
wechat_ide(action="open")
wechat_automator(action="start")
wechat_automator(action="page_data")

端口规则：

• wechat_ide(action="status") 识别到的是微信开发者工具 CLI 服务端口，只用于 open / compile / preview 等 CLI 命令。
• 截图、页面跳转、console 日志和元素自动化走 miniprogram-automator WebSocket 自动化端口，默认是 9420。
• 通常不要传 auto_port。先调用一次 wechat_automator(action="start")，后续直接用 wechat_screenshot / wechat_navigate / wechat_inspector。
• 如果误把识别出来的 CLI 服务端口传给 auto_port，服务端会自动回落到默认自动化端口，并在返回数据里给出 warning。

代码修改后：

wechat_build(action="compile")
wechat_automator(action="page_data")
wechat_inspector(action="console")

页面调试：

wechat_file(action="list_pages")
wechat_navigate(page_path="pages/index/index", wait_ms=1000)
wechat_automator(action="page_data")
wechat_screenshot()

元素操作：

wechat_automator(action="tap", selector=".wx-login-btn")
wechat_automator(action="input", selector="input", value="hello")
wechat_automator(action="element_info", selector=".target")

工具列表

所有工具都返回统一 JSON 信封：

{
  "success": true,
  "data": {},
  "message": "操作描述"
}

失败时返回：

{
  "success": false,
  "error_code": "ERROR_CODE",
  "message": "失败原因",
  "hint": "可选修复建议"
}

| Tool | 用途 | | --- | --- | | wechat_ide | open / login / is_login / close / quit / status | | wechat_build | compile / preview / upload / build_npm / cache_clean | | wechat_automator | start、点击、输入、读取元素、读取页面 data、调用页面方法、调用 wx API、mock、evaluate、storage、scroll、reload | | wechat_inspector | 采集 automator console / exception 日志，仅 action="console" | | wechat_screenshot | 截图，默认保存到当前项目 screenshots/screenshot_<timestamp>.png | | wechat_navigate | 自动判断 tabBar 并跳转页面，同时返回页面栈、页面 data 和运行时日志 | | wechat_file | 读取项目配置、页面列表、页面源码、单文件 | | agents | 读取随 npm 包发布的 .agents skill 信息 |

截图与日志

截图：

wechat_screenshot()

默认保存到：

<当前项目>/screenshots/screenshot_<timestamp>.png

也可以指定路径：

wechat_screenshot(output_path="/tmp/home.png")

日志：

wechat_inspector(action="console", duration=3, detail_level="full")

截图和日志都通过 miniprogram-automator SDK 完成，不需要额外调试端口。

AI 如何读取 npm 包中的 Skills

本包内置 skill：

.agents/skills/wechat-devtools/SKILL.md

支持 MCP resources 的 AI 客户端可以读取：

skill://wechat-devtools

如果客户端不主动读取 resource，可以调用工具兜底：

agents(action="read", name="wechat-devtools")

其他相关调用：

agents(action="list")
agents(action="path")

说明：MCP Server 可以把 skill 暴露成 resource 或工具结果，但是否在调用其他工具前自动塞进模型上下文，取决于具体 AI 客户端。建议客户端在连接 MCP 后先读取 skill://wechat-devtools，或先调用 agents(action="read", name="wechat-devtools")。

常见问题

找不到项目

确认当前 workspace 是 uniapp 项目根目录，或者手动传入 project_path。uniapp 需要先生成微信小程序产物：

unpackage/dist/dev/mp-weixin

AppID 为空

确认最终解析到的是微信小程序目录，并且里面有有效的 project.config.json。

automator 连接失败

先确认：

• 微信开发者工具服务端口已开启
• 已通过 wechat_ide(action="open") 打开项目
• 项目 AppID 有效
• 不要把 CLI 服务端口传给 auto_port；自动化通常使用 9420

然后重试：

wechat_automator(action="start")

元素点不到

先读取页面和源码：

wechat_automator(action="page_data")
wechat_file(action="read_page", page_path="pages/login/index")

确认页面路径和真实 selector 后再调用 tap。

开发

运行测试：

npm test

检查发布包内容：

npm pack --dry-run --json