Wechat Devtools Mcp

微信开发者工具 MCP Server (v0.9.10)

[](https://pypi.org/project/wechat-devtools-mcp/) [](https://modelcontextprotocol.io/docs/concepts/mcp-registry) [](https://opensource.org/licenses/MIT) [](./README_EN.md)

> 将微信开发者工具 CLI 封装为 MCP (Model Context Protocol) 服务，使编辑器中的 AI 能够直接调用微信 CLI 命令，实现小程序开发、测试、调试、自动化全流程闭环。

> [!IMPORTANT] > 本项目采用「瘦 MCP + 胖 Skill」架构：MCP Server 提供 7 个聚合 API，配套的 [wechat-devtools Skill](#-安装-skill必须) 提供 SOP 流程、参数速查和最佳实践。两者必须配合使用，缺少 Skill 时 AI 将无法按正确流程操作小程序。

已发布至官方 MCP Registry，支持跨平台（Windows / macOS）一键安装。

---

> 🌐 [English Documentation →](./README_EN.md)

---

🚀 安装与快速开始

Step 1 — 安装 MCP Server

推荐使用 uv，它能自动处理 Python 依赖并提供隔离的执行环境。

pip install uv                                  # 安装 uv（如已安装可跳过）
uv tool install wechat-devtools-mcp --force     # 一键安装到全局隔离环境

> [!WARNING] > 如果之前通过 pip install 安装过旧版本，请先卸载以避免版本冲突： > ``bash > pip uninstall wechat-devtools-mcp > ` > pip install 的路径（如 Python313/Scripts/）可能优先于 uv tool install 的路径（~/.local/bin/），导致实际运行旧版本。可通过 wechatide(action='status') 返回的 mcpversion` 字段确认当前版本。

> [!TIP] > - 查看已安装版本： > ``bash > uv tool list | grep wechat # 离线确认已安装版本 > ` > - 升级工具：如果编辑器正在运行 MCP 服务，需先终止进程再升级： > `bash > # Bash / CMD > taskkill /F /IM "wechat-devtools-mcp*" 2>/dev/null; uv tool upgrade wechat-devtools-mcp > ` > `powershell > # Windows PowerShell > Get-Process | Where-Object { $_.ProcessName -like "*wechat-devtools*" } | Stop-Process -Force > uv tool upgrade wechat-devtools-mcp > ` > - Agent 一键升级： > `bash > taskkill /F /IM "wechat-devtools-mcp*" 2>/dev/null; uv tool upgrade wechat-devtools-mcp && npx -y skills add WaterTian/wechat-devtools-mcp/.agents/skills/wechat-devtools > ``

Step 2 — 开启开发者工具服务端口

> [!WARNING] > 必须手动开启，否则 AI 将无法下发任何指令。

操作路径：开发者工具 → 设置 → 安全设置 → 服务端口 → 开启

> 💡 可通过 wechat_ide(action='status') 验证端口是否已开启——如果返回连接失败，说明服务端口尚未启用。

Step 3 — 确认必要路径

请提前获取以下两个绝对路径，稍后需填入编辑器配置：

| 路径 | Windows 示例 | macOS 示例 | |------|-------------|-----------| | 微信开发者工具 CLI | C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat | /Applications/wechatwebdevtools.app/Contents/MacOS/cli | | 小程序项目根目录 | D:\MyProjects\mini-app | /Users//Projects/mini-app |

> macOS 用户：JSON 配置中无需转义斜杠（/ 直接写）；Windows 用户需把 \ 写成 \\。

Step 4 — 编辑器配置

Claude Desktop / Antigravity

修改 claude_desktop_config.json 或 mcp_config.json（Antigravity）：

{
  "mcpServers": {
    "wechat-devtools": {
      "command": "uvx",
      "args": ["wechat-devtools-mcp"],
      "env": {
        "WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat",
        "WECHAT_PROJECT_PATH": "D:\\Your\\Project\\Path"
      }
    }
  }
}

Kiro

编辑 ~/.kiro/settings/mcp.json：

{
  "mcpServers": {
    "wechat-devtools": {
      "command": "uvx",
      "args": ["wechat-devtools-mcp"],
      "env": {
        "WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat",
        "WECHAT_PROJECT_PATH": "D:\\Your\\Project\\Path",
        "PYTHONIOENCODING": "utf-8"
      },
      "autoApprove": [
        "wechat_ide", "wechat_build", "wechat_automator", "wechat_inspector",
        "wechat_screenshot", "wechat_navigate", "wechat_file"
      ]
    }
  }
}

OpenAI Codex

编辑 ~/.codex/config.toml（全局）或 .codex/config.toml（项目级）：

[mcp_servers.wechat-devtools]
command = "uvx"
args = ["wechat-devtools-mcp"]

[mcp_servers.wechat-devtools.env]
WECHAT_DEVTOOLS_CLI = "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat"
WECHAT_PROJECT_PATH = "D:\\Your\\Project\\Path"

也可以通过 CLI 快速添加：

codex mcp add wechat-devtools \
  --env WECHAT_DEVTOOLS_CLI="C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat" \
  --env WECHAT_PROJECT_PATH="D:\\Your\\Project\\Path" \
  -- uvx wechat-devtools-mcp

Cursor / VS Code (MCP Plugin)

在 MCP 控制台中添加新 Server：

• Name: wechat-devtools
• Type: command
• Command: uvx wechat-devtools-mcp
• Environment Variables: 同上添加 WECHAT_DEVTOOLS_CLI 和 WECHAT_PROJECT_PATH

> Windows 下路径中的反斜杠需要转义（\\）。

Claude Code 项目级 .mcp.json（仓库内开发推荐）

如果你用 Claude Code 在小程序仓库里开发，可以建项目级 .mcp.json（自动跟随仓库、对协作者生效）。

Windows — 仓库根目录 .mcp.json：

{
  "mcpServers": {
    "wechat-devtools": {
      "command": "uvx",
      "args": ["wechat-devtools-mcp"],
      "env": {
        "WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat",
        "WECHAT_PROJECT_PATH": "D:\\Your\\Project\\Path"
      }
    }
  }
}

macOS — 仓库根目录 .mcp.json：

{
  "mcpServers": {
    "wechat-devtools": {
      "command": "/opt/homebrew/bin/uvx",
      "args": ["wechat-devtools-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
        "WECHAT_DEVTOOLS_CLI": "/Applications/wechatwebdevtools.app/Contents/MacOS/cli",
        "WECHAT_PROJECT_PATH": "/Users//WeChatProjects/",
        "NODE_PATH": "/opt/homebrew/bin/node"
      }
    }
  }
}

> macOS 三个关键差异： > - command 必须用绝对路径 /opt/homebrew/bin/uvx（Claude Code spawn 子进程时 PATH 不含 Homebrew） > - env.PATH 必须显式注入（同时配 npx-based MCP 如 cloudbase / chrome-devtools 时尤其需要，否则 npx 的 #!/usr/bin/env node 找不到 Node） > - NODE_PATH 推荐显式指定，作为 daemon 启动时的双保险

> 同时配置多个 MCP（cloudbase / chrome-devtools 等）时，每个 server 都按相同模式处理 command 绝对路径与 env.PATH。

Trae IDE（全局 mcp.json）

Trae v1.3.0+ 支持 MCP。AI 面板 → 右上角设置 → MCP → 添加 → 手动配置，粘贴下方 JSON 后保存。

Windows：

{
  "mcpServers": {
    "wechat-devtools": {
      "command": "uvx",
      "args": ["wechat-devtools-mcp"],
      "env": {
        "WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat",
        "WECHAT_PROJECT_PATH": "D:\\Your\\Project\\Path"
      }
    }
  }
}

macOS：

{
  "mcpServers": {
    "wechat-devtools": {
      "command": "/opt/homebrew/bin/uvx",
      "args": ["wechat-devtools-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
        "WECHAT_DEVTOOLS_CLI": "/Applications/wechatwebdevtools.app/Contents/MacOS/cli",
        "WECHAT_PROJECT_PATH": "/Users//WeChatProjects/",
        "NODE_PATH": "/opt/homebrew/bin/node"
      }
    }
  }
}

直接编辑配置文件也可：

• Windows: %APPDATA%\Trae\User\globalStorage\mcp.json
• macOS: ~/Library/Application Support/Trae/User/globalStorage/mcp.json

> [!IMPORTANT] > 聊天框必须选 「Builder with MCP」 智能体，普通智能体不调 MCP 工具。建议同时安装 wechat-devtools Skill（Step 5），让 AI 按 SOP 顺序调用。

Step 5 — 安装 Skill（必须）

> [!IMPORTANT] > 本 MCP 必须配合 wechat-devtools Skill 使用。 Skill 包含 AI 操作小程序所需的全部 SOP 流程、参数速查和故障排查指南。未安装 Skill 时，AI 只能调用裸 API，无法自动执行标准化测试和调试流程。

方式一：npx skills add（Claude Code 用户）

npx -y skills add WaterTian/wechat-devtools-mcp/.agents/skills/wechat-devtools

会拉到 ~/.claude/skills/，Claude Code 自动加载。

方式二：手动放到 .agents/skills/（Trae 等基于 .agents/skills/ 加载的客户端）

在小程序项目根目录执行：

git clone --depth 1 https://github.com/WaterTian/wechat-devtools-mcp.git .wdm-tmp
mkdir -p .agents/skills
cp -r .wdm-tmp/.agents/skills/wechat-devtools .agents/skills/
rm -rf .wdm-tmp

完成后的目录结构：

your-project/
└── .agents/skills/
    └── wechat-devtools/
        ├── SKILL.md                # 主指令文件（SOP + 能力映射 + 红线规则）
        └── references/
            └── tool_reference.md   # 7 个聚合 API 完整参数参考

> [!TIP] > Trae 用户：确认 设置 → 技能与命令 → 启用 .agents 技能目录 开关已开启（默认开），保存后刷新即可在「技能 → 项目」tab 看到 wechat-devtools。

---

🛠️ 工具箱概要

MCP Server 提供 7 个聚合工具，覆盖小程序全生命周期：

| 工具 | 功能 | 支持的 action | |------|------|--------------| | wechat_ide | IDE 生命周期管理 | open login is_login close quit status | | wechat_build | 构建与发布 | compile preview upload build_npm cache_clean | | wechat_automator | 自动化交互 | start tap input element_info set_data call_method call_wx mock_wx evaluate page_stack page_data system_info storage | | wechat_inspector | 运行时日志采集 | console cdp | | wechat_screenshot | 界面截图（长图拼接） | — | | wechat_navigate | 跳转页面并采集 CDP 日志 | — | | wechat_file | 项目文件读取 | project_info list_pages read_page read_file |

> 云函数与云数据库管理请使用 CloudBase MCP（manageFunctions / readNoSqlDatabaseContent 等），功能更完整且无 IDE 依赖。wechat_cloud 自 v0.9.5 起已禁用。 > > 完整工具参数说明请参阅 [MCPDOC.md](./MCP_DOC.md)

---

🧠 Skill 内容详情

Skill 让 AI 在收到自然语言指令后，自动匹配并执行标准化操作流程：

| 你说的话 | AI 执行的流程 | |---------|--------------| | "帮我检查所有页面有没有报错" | SOP D — 全页面巡检 | | "点击登录按钮，截图看看效果" | SOP B — UI 调试 | | "页面白屏了，帮我排查" | SOP C — 异常排查 | | "Mock 支付接口，测试支付流程" | SOP E — Mock 集成测试 | | "测试详情页，参数名是什么" | SOP G — 子页面测试 | | "对比各页面积分是否一致" | SOP I — 跨页面数据校验 |

Skill 包含

• 9 个 SOP 流程 — 初始化、UI 调试、异常排查、全页面巡检、Mock 集成测试、网络调试与 UI 适配、子页面测试、跨页面数据校验、并行数据比对
• 能力映射字典 — 7 个聚合工具 × 全部 action 的快速索引
• CDP 渐进排查策略 — concise → full 两阶段，控制 Token 消耗
• 完整参数参考 — 每个 action 的必填/可选参数、返回示例、常用模板
• 故障排查手册 — 常见错误码与修复方式

> 安装方式见 [Step 5 — 安装 Skill](#step-5--安装-skill必须)

---

💡 环境变量

| 变量名 | 说明 | 默认值 | 必填 | |--------|------|--------|------| | WECHAT_DEVTOOLS_CLI | 微信开发者工具 CLI 路径 | — | 是 | | WECHAT_PROJECT_PATH | 默认小程序项目绝对路径 | — | 是 | | WECHAT_CLI_TIMEOUT | CLI 命令超时时间（秒） | 30 | 否 | | NODE_PATH | Node.js 执行文件路径 | node | 否 |

---

❓ 常见问题

为什么 AI 总是报 CLI_TIMEOUT 错误？

最常见原因：微信开发者工具的"服务端口"未开启。 进入 设置 → 安全 → 服务端口，将其打开。开启后无需重启 IDE，AI 即可恢复连接。

wechat_inspector 返回"CDP 采集失败"

如果手动打开了开发者工具，它可能未监听调试端口。请关闭开发者工具，让 AI 执行 wechat_ide(action='open', cdp_enabled=True) 以调试模式启动。

uv tool upgrade 提示文件被占用？

编辑器中的 MCP 服务仍在运行。参见 [Step 1](#step-1--安装-mcp-server) 下方的升级提示——需先终止进程再升级。

uv tool install 后仍运行旧版本？

可能是 pip install 安装的旧版本优先级更高。运行 pip uninstall wechat-devtools-mcp 移除旧版本，然后通过 wechat_ide(action='status') 确认 mcp_version 字段为最新版本。

AI 无法找到微信 CLI 路径？

在编辑器配置的 env 中确保 WECHAT_DEVTOOLS_CLI 填入了绝对路径：

• Windows: 使用双反斜杠（如 C:\\...\\cli.bat）
• macOS: 标准路径 /Applications/wechatwebdevtools.app/Contents/MacOS/cli，斜杠无需转义

macOS 上 Node.js 检测失败？

GUI 客户端（如 Claude Desktop）启动 MCP 时 PATH 可能不包含 /opt/homebrew/bin。MCP v0.9.6 起会自动尝试 Homebrew 标准路径；若仍失败，可在 env 中显式设置：

"NODE_PATH": "/opt/homebrew/bin/node"

---

📋 版本历史

| 版本 | 说明 | |------|------| | 0.9.10 | 修复 pagepath 静默失败：screenshot.js 导航后验证页面路径是否匹配，缺少 /index 后缀或页面不存在时返回明确错误而非静默拍下旧页面；nodebridge.py 修复 daemon handler 错误信息丢失（#5）| | 0.9.9 | 修复截图导致小程序重启：screenshot.js 对非 TabBar 页面的导航方式从 reLaunch（销毁全部页面栈）改为 navigateTo（非破坏性压栈），修复 macOS 环境下截图后模拟器重置问题（#4）| | 0.9.8 | 修复 automator 连接稳定性：daemon.js currentPage() 健康检查改为轮询重试（新连接 5 次 × 3s+1.5s），不再因页面加载慢丢弃已建立的 WebSocket 连接；_action_start 改用 _run_cli 同步检测 CLI 返回码，CLI 失败立即感知（#3）| | 0.9.7 | 修复 daemon 孤儿进程残留：daemon.js 增加父进程 watchdog，每 5 秒 process.kill(ppid, 0) 检测存活，父进程被杀后自动清理 WS 连接并退出（#2）| | 0.9.6 | macOS 适配：cdp_enabled=true 模式跨平台启动（NW.js 主程序 wechatdevtools + package.nw 入口 + pkill 清理）；默认 CLI 路径按平台返回；Node.js 检测补 Homebrew/nvm 候选路径；README 增加 macOS 路径示例 | | 0.9.5 | 修复 compile 健康检查永久失败的潜伏 bug（ui_debug.js 无 page_stack action，v0.9.0 以来 automator_verified 一直误报 false）；compile 对 EACCES/EADDRINUSE/#initialize-error 等致命 pattern 降级为 fail，杜绝「假成功发布旧 bundle」；preview 自动 resolve 相对路径 + mtime 新鲜度检测；wechat_automator(action='start') 升级为 TCP+WS 双重验证 + retry_after_ms 精确等待；compile 前检测 miniprogram_npm 过期发 warning；inspector 短 duration 捕获异常时发 warning；wechat_cloud 工具已禁用（改用 CloudBase MCP） | | 0.9.4 | 修复 switchTab 跳转不生效（改用 miniProgram.switchTab() 替代 callWxMethod）；compile 后重连稳定性（去冗余进程 + 3s 延迟 + WS 健康检查）；README 5 项 agent 友好性改进 |

展开 v0.9.3 及更早版本

| 版本 | 说明 | |------|------| | 0.9.3 | status 新增 mcp_version 字段用于版本确认；启动时打印版本号到 stderr；README 增加 pip/uv 版本冲突排查指引 | | 0.9.2 | 修复 compile 后 navigate 超时：daemon 连接健康检查增加 3s 超时保护；compile 后自动 invalidate 旧缓存连接再重连；navigate currentPage 轮询每次调用增加 2s 独立超时；区分 HEALTH\CHECK\TIMEOUT 和 CONNECTION\ERROR 错误码 | | 0.9.1 | 修复 cdp\enabled=true 时 AttributeError 崩溃；新增 WXML 运行时错误采集（compile 后 CDP 自动捕获 template not found 等警告） | | 0.9.0 | 持久化 Node daemon 架构：单 daemon 进程常驻，NDJSON 协议通信，WS 连接按端口复用；单个 daemon.bundle.js 替代 8 个独立 bundle；工具调用延迟从 500ms+ 降至 ~3ms；compile 后 daemon 自动重建连接零断连 | | 0.8.0 | compile 后自动重连 automator；navigate 自动识别 TabBar 页面走 switchTab；screenshot 新增 full\page/scroll\top/page\path 参数及视口截图模式；page\data 新增 expected\path 轮询防旧数据；长图拼接动态步长修复内容缺口；node\bridge 统一连接断开重试 + 500ms 调用间隔；start 端口验证增至 20 次 | | 0.7.0 | navigate 变量作用域修复（currentPageTimeout）；evaluate 支持声明语句（const/let/var fallback）；callmethod 返回当前页面路径；automator start 端口轮询验证替代盲等；SKILL.md 新增效率原则、恢复分级、页面跳转方法、6 条故障条目 | | 0.6.0 | navigate 支持 query 参数（reLaunch 超时 fallback）；CDP 启动噪音过滤（console.assert/\\route\\/ide:// 降噪 + WXML 错误保护）；compile 返回值三分类 + automator 失效提示；navigate currentPage 轮询重试；超时可配置 | | 0.5.1 | wechat_ide(action='open') 新增 CDP 启动健康检查：自动采集 5 秒 CDP 日志检测启动阶段致命错误，有错误直接返回失败阻止后续操作 | | 0.5.0 | Skill SOP 全面优化：新增 SOP I/J；增加 AppID 检查与 path 校验；CDP 噪音过滤；截图拼接模糊匹配修复 | | 0.4.1 | 截图长页面拼接重写：固定区域检测、DPR 自适应、动态重叠计算 | | 0.4.0 | CDP 日志增强、云函数部署自动验证、navigate 智能诊断、新增 SOP G/H | | 0.3.0 | 重大重构：44 个工具聚合为 8 个 API；CDP 日志 v2；新增 SKILL.md 知识库 | | 0.2.6 | README 新增 OpenAI Codex 配置说明 | | 0.2.5 | 新增 Kiro 编辑器配置说明 | | 0.2.4 | 截图滚动拼接修复：sharp → jimp | | 0.2.3 | 发布包优化：排除 scripts/ 源码，仅保留 dist/ 构建产物 | | 0.2.2 | Node.js 脚本改为 bundle-only 模式 | | 0.2.1 | 版本更新与文档完善 | | 0.2.0 | navigate 改用 CDP 高清日志采集 | | 0.1.9 | 修复 UTF-8 编码乱码 | | 0.1.8 | 修复 Windows 中文路径 UnicodeDecodeError | | 0.1.7 | 新增 core/full 工具集预设；新增 MCPDOC.md | | 0.1.6 | wechat_open(cdp_enabled=true) 自动 kill 已有进程 | | 0.1.5 | 修复 Windows stdio 阻塞问题 | | 0.1.4 | 添加 CDP 日志、截图、自动化等功能 | | 0.1.3 | 初始版本 |

---

参考文档

• 微信开发者工具 CLI 官方文档
• 小程序自动化 SDK

---

---

许可证

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: WaterTian
• Source: WaterTian/wechat-devtools-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.