Wechat Dev Mcp

微信开发者工具 MCP Server

用自然语言驱动微信开发者工具，让 AI 帮你启动项目、调试小程序 / 小游戏、跑自动化。

🇺🇸 English · 🇨🇳 中文

---

通过 Model Context Protocol (MCP) 控制微信开发者工具，以及上面的 小程序（mini-program）和 小游戏（mini-game）。兼容 WorkBuddy、Claude Code、OpenAI Codex、OpenCode、Claude Desktop、Cursor、Windsurf、Cline、Zed 等客户端。

> 一句话就能让 AI： > - 小程序：「打开我的小程序 → 跳到首页 → 点击登录按钮 → 截图看看效果」 > - 小游戏：「打开小游戏 → 在 (2,10) 格点一下 → 抓张截图 → 导出 vConsole 日志」

---

🤝 配合 wechat-dev-skill 一起用（强烈推荐）

这个 MCP 提供的是原子工具（"肌肉"）：连接、截图、触控、读日志……一个个调。调试时你真正想要的是一条固定流程（"routine"）——wechat-dev-skill 就是这个流程封装：

| | 角色 | 你得到什么 | |---|---|---| | wechat-dev-mcp（本仓库） | 原子工具层 | check_health / game_touch / game_canvas_screenshot / restart_project … 40+ 个可被 AI 调用的工具 | | wechat-dev-skill（配套 skill） | 例行巡检流程 | 一条命令跑完「健康 → 编译 → 控制台 → 网络 → 截图 → 功能测试」并出简报 |

怎么配合：两个一起装上即可。调试时让 AI 直接排查问题，它会按需调用本 MCP 的工具，按 skill 封装的巡检流程自动定位报错、验证功能。

• MCP 安装见下方「🚀 快速开始」。
• wechat-dev-skill 配套仓库：https://github.com/jiawei686/wechat-dev-skill

---

🚀 快速开始

1. 安装 MCP Server

方式一：npx 直接运行（最快上手）

npx -y wechat-dev-mcp

方式二：全局安装（推荐，启动更快）

npm install -g wechat-dev-mcp

方式三：本地开发

git clone https://github.com/jiawei686/wechat-dev-mcp.git
cd wechat-dev-mcp
npm install
node index.js

2. 接入你的 MCP 客户端

所有客户端的 stdio 命令都一致，区别仅在配置文件位置。以 Cursor 为例，编辑 ~/.cursor/mcp.json（或项目内 .cursor/mcp.json）：

{
  "mcpServers": {
    "wechat-devtools": {
      "command": "npx",
      "args": ["-y", "wechat-dev-mcp"]
    }
  }
}

仓库已内置 .cursor/mcp.json 与 .mcp.json，亦可导入 [examples/cursor-mcp-config.json](examples/cursor-mcp-config.json)（含环境变量示例）。 其它客户端（Claude Code / Desktop、Codex、OpenCode、Windsurf、Cline、Zed）配置方式见各自文档，命令相同。

3. 前置条件

| 要求 | 说明 | |------|------| | Node.js | v18+ | | 微信开发者工具 | 已安装，并开启 服务端口（设置 → 安全设置 → 服务端口） | | 小程序 / 小游戏 | 在开发者工具中已打开的项目（project.config.json 含 compileType） |

> ⚠️ 必须先开启「服务端口」，否则会报 Connection refused。

4. 连接并验证

让 AI：
  1. 连接项目：connect({ projectPath: "/绝对路径/你的工程" })
                  或 launch({ projectPath: "/绝对路径/你的工程" })
  2. 健康检查：  check_health()   ← 每次改代码后都要跑

小游戏若 automator(9420) 不可用，但 DevTools 以 --remote-debugging-port=9222 启动了，传 cdpEndpoint（或让 server 自动发现）即可走 CDP-only 模式，足以支撑 console/网络/截图/触控全部能力。

---

🎮 小游戏重点能力（含最新工具）

小游戏连接后以下能力自动生效；其中三个是本项目最新加的"调试利器"：

⭐ game_tap_grid(row, col) — 以棋盘格落子（最推荐）

不用算像素，直接说"在第 2 行第 10 列落子"。内部把格坐标换成逻辑像素、自动套用触控仿射变换确保精确命中，并默认截图差分确认棋子真的落在 (row,col)。

{ "name": "game_tap_grid", "arguments": { "row": 2, "col": 10, "verify": true } }

⭐ set_touch_map(sx, sy, ox, oy) — 触控坐标标定

模拟器缩放 / 窗口位置变了导致落点偏移时，重新标定。变换关系：MCP 发送 S = (ox, oy) + (sx, sy)·L（L = 目标逻辑坐标）。本机默认值 sx=sy=0.75, ox=37.75, oy=91.0，一般不用动。

⭐ restart_project(projectPath) — 安全重开 / 重编译

崩溃恢复、或改完代码要重新编译时调用，底层 cli open --auto-test --project ，干净拉起运行时。绝不要用 CDP Page.reload 重开游戏——实测会让游戏运行时崩溃且无法自恢复。

其它小游戏工具

game_touch（画布坐标触控）、game_canvas_screenshot（画布全屏截图）、game_get_fps、game_webgl_debug、game_get_network_logs、game_export_vconsole、game_get_info 等。完整文档见 👉 [docs/MINIGAMEGUIDE.md](docs/MINIGAMEGUIDE.md)。

> 坐标空间（实测确认）：模拟器里 CDP 触控坐标与游戏逻辑坐标之间是仿射变换而非 1:1。MCP 已内置补偿（touchMap），所以 game_tap_grid / game_touch 直接传逻辑坐标即可精确命中；偏移时用 set_touch_map 重标定。

---

🔧 环境变量

| 变量 | 默认值 | 说明 | |------|--------|------| | WECHAT_PORT | 9420 | WebSocket 自动化端口 | | WECHAT_GAME_CDP_PORT | 9420 | 小游戏 CDP 端口（自动发现失败时参考） | | WECHAT_CLI_TIMEOUT | 120000 | CLI 命令超时（毫秒） | | WECHAT_AUTOMATOR_TIMEOUT | 10000 | 自动化 API 超时（毫秒） | | WECHAT_MAX_LOG_ENTRIES | 400 | 日志仓库最大条目 |

---

❓ 常见问题

| 问题 | 解决方案 | |------|----------| | Connection refused | 确保开发者工具已运行，且「服务端口」已开启 | | 小游戏连接失败 / 通道断开 | server 已用 GameGlobal 存活探测 + 自动重连；仍失败可 disconnect 后重连 | | 页面工具在小游戏上不可用 | 预期行为：小游戏自动屏蔽 DOM 工具，改用 game_touch / evaluate | | game_touch 提示无触控监听 | 游戏尚未注册触控回调（未进入可交互界面），先 evaluate 触发开始逻辑 | | 落子位置不对 | 用 game_tap_grid（已含坐标补偿）；若仍偏，用 set_touch_map 重新标定 | | CDP 未连接 | 手动 set_cdp_endpoint 设置 webSocketDebuggerUrl；否则回退 evaluate 方案 | | 游戏崩溃 / 卡死 | 用 restart_project 重开；不要对游戏 webview 调 Page.reload | | CLI 未找到 | 显式传入 cliPath 或检查安装路径 |

---

📂 项目结构

wechat-dev-mcp/
├── index.js              # 入口（stdio 启动）
├── src/
│   ├── config.js         # 常量 / 环境变量 / CLI 辅助（含 spawnCli / waitGameWebview）
│   ├── state.js          # 运行时单例状态
│   ├── detector.js       # 项目类型 / 引擎检测
│   ├── cdp-client.js      # 小游戏 CDP 客户端（含 touchMap 仿射变换）
│   ├── board-vision.js    # 棋盘视觉分析（detectBoard / findNewStone / stoneToGrid）
│   ├── connection.js      # 连接管理（双模式 + 保活）
│   ├── game-runtime.js    # 小游戏插桩与交互
│   ├── server.js          # MCP Server 组装
│   └── tools/            # 工具定义与分发
│       ├── common.js      # 通用 / 小游戏工具（含 game_tap_grid / set_touch_map / restart_project）
│       ├── program.js     # 仅小程序工具
│       ├── game.js        # 仅小游戏工具
│       └── registry.js    # 工具注册 / 按类型屏蔽
├── docs/
│   └── MINIGAME_GUIDE.md # 小游戏使用文档
├── examples/
│   └── cursor-mcp-config.json  # Cursor 可导入配置示例
├── package.json
├── AGENTS.md
├── README.md / README_EN.md
└── .cursorrules

---

🤝 贡献与许可证

欢迎提交 Issue 和 PR！如果你在其它 MCP 客户端上成功接入，欢迎补充配置示例。

[MIT License](LICENSE) © CuiJiawei

Source & license

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

• Author: jiawei686
• Source: jiawei686/wechat-dev-mcp
• License: MIT

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