Wechat Devtools MCP Server

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

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

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

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

---

🌐 English Documentation →

---

🚀 安装与快速开始

Step 1 — 安装 MCP Server

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

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

[!WARNING] 如果之前通过 pip install 安装过旧版本，请先卸载以避免版本冲突：

pip uninstall wechat-devtools-mcp

pip install 的路径（如 Python313/Scripts/）可能优先于 uv tool install 的路径（~/.local/bin/），导致实际运行旧版本。可通过 wechat_ide(action='status') 返回的 mcp_version 字段确认当前版本。

[!WARNING] 版本兼容性：≥0.9.11 支持 mcp 1.x 与 2.x 双版本（依赖声明 mcp[cli]>=1.9,<3）。≤0.9.10 与 mcp ≥2.0 不兼容（新装会报 ModuleNotFoundError: mcp.server.fastmcp，见 #9）--钉版用户请升级到 ≥0.9.11，或安装时追加 --with "mcp<2"。

[!TIP]

• 查看实际运行版本（≥0.9.13）：

  wechat-devtools-mcp --version    # 零依赖打印实际安装版本；uvx 复用已装环境不自拉最新，此命令可直接确认
  uv tool list | grep wechat       # 离线确认已安装版本
  

• 升级工具：如果编辑器正在运行 MCP 服务，需先终止进程再升级：

  # Bash / CMD
  taskkill /F /IM "wechat-devtools-mcp*" 2>/dev/null; uv tool upgrade wechat-devtools-mcp
  

  # Windows PowerShell
  Get-Process | Where-Object { $_.ProcessName -like "*wechat-devtools*" } | Stop-Process -Force
  uv tool upgrade wechat-devtools-mcp
  

• Agent 一键升级：

  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 — 确认必要路径

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

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

Step 4 — 编辑器配置

修改 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/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"
      ]
    }
  }
}

编辑 ~/.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

在 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（自动跟随仓库、对协作者生效）。

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/<you>/WeChatProjects/<project>",
        "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 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/<you>/WeChatProjects/<project>",
        "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 个聚合工具，覆盖小程序全生命周期：

云函数与云数据库管理请使用 CloudBase MCP（manageFunctions / readNoSqlDatabaseContent 等），功能更完整且无 IDE 依赖。wechat_cloud 自 v0.9.5 起已禁用。

完整工具参数说明请参阅 MCP_DOC.md

---

🧠 Skill 内容详情

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

Skill 包含

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

安装方式见 Step 5 — 安装 Skill

---

💡 环境变量

---

❓ 常见问题

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

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

编辑器中的 MCP 服务仍在运行。参见 Step 1 下方的升级提示——需先终止进程再升级。

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

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

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

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

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

---

📋 版本历史

---

参考文档

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

---

许可证

MIT