wechat-devtools-mcp
A WeChat DevTools MCP server that lets an editor's AI compile, preview, debug, and automate-test mini programs through 7 aggregated tools.
wechat_ide — manage IDE lifecycle and diagnose the environment:
open,login,is_login,close,quit,status(checks CLI/project paths, service port, CDP port occupant, skill version).wechat_build — build and release:
compile,preview,upload,build_npm,cache_clean.wechat_automator — drive the running mini program:
start,tap,input,element_info,set_data,call_method,call_wx,mock_wx,evaluate(expression or full function source),page_stack,page_data,system_info,storage.wechat_inspector — collect runtime logs:
console(automator console logs + JS exceptions) andcdp(WXML warnings, render-layer errors, deprecated API notices, with history replay).wechat_screenshot — capture the simulator, including auto-scrolled stitched full-page long screenshots; supports viewport-only, scroll position, page path, and
wait_for_selector.wechat_navigate — jump to a page (with query params), wait, and gather CDP logs for lifecycle/error verification.
wechat_file — read project structure and source:
project_info,list_pages,read_page,read_file.
Provides integration with WeChat Developer Tools to automate WeChat Mini Program development, testing, debugging, UI inspection, screenshot capture, navigation, and project file management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@wechat-devtools-mcp 打开项目并预览"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
WeChat DevTools MCP Server (v0.9.15)
Wraps the WeChat DevTools CLI as an MCP (Model Context Protocol) service, allowing AI in editors to directly invoke WeChat CLI commands, enabling a closed loop for mini program development, testing, debugging, and automation.
[!IMPORTANT] This project adopts a "thin MCP + fat Skill" architecture: the MCP Server provides 7 aggregated APIs, and the accompanying wechat-devtools Skill provides SOP workflows, parameter quick references, and best practices. Both must be used together — without the Skill, the AI will not be able to operate mini programs following the correct workflow.
Published to the official MCP Registry, with one-click installation across platforms (Windows / macOS).
🚀 Installation and Quick Start
Step 1 — Install the MCP Server
uv is recommended, as it automatically handles Python dependencies and provides an isolated execution environment.
pip install uv # 安装 uv(如已安装可跳过)
uv tool install wechat-devtools-mcp --force # 一键安装到全局隔离环境[!WARNING] If you previously installed an older version via
pip install, uninstall it first to avoid version conflicts:pip uninstall wechat-devtools-mcpThe
pip installpath (e.g.Python313/Scripts/) may take precedence over theuv tool installpath (~/.local/bin/), causing the old version to actually run. You can confirm the current version via themcp_versionfield returned bywechat_ide(action='status').
[!WARNING] Version compatibility: ≥0.9.11 supports both mcp 1.x and 2.x (dependency declared as
mcp[cli]>=1.9,<3). ≤0.9.10 is incompatible with mcp ≥2.0 (fresh installs will reportModuleNotFoundError: mcp.server.fastmcp, see #9) — pinned users should upgrade to ≥0.9.11, or append--with "mcp<2"when installing.
[!TIP]
Check the actually running version (≥0.9.13):
wechat-devtools-mcp --version # 零依赖打印实际安装版本;uvx 复用已装环境不自拉最新,此命令可直接确认 uv tool list | grep wechat # 离线确认已安装版本Upgrading the tool: if the editor is running the MCP service, terminate the process before upgrading:
# 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-mcpOne-click upgrade via 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 — Enable the DevTools Service Port
[!WARNING] This must be enabled manually, otherwise the AI will not be able to send any commands.
Path: DevTools → Settings → Security Settings → Service Port → Enable
💡 You can verify whether the port is enabled via
wechat_ide(action='status')— if it returns a connection failure, the service port has not been enabled yet.
Step 3 — Confirm Required Paths
Obtain the following two absolute paths in advance; you will need to fill them into the editor configuration later:
Path | Windows example | macOS example |
WeChat DevTools CLI |
|
|
Mini program project root |
|
|
macOS users: no need to escape slashes (
/) in JSON config; Windows users must write\as\\.
Step 4 — Editor Configuration
Modify claude_desktop_config.json or 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"
}
}
}
}Edit ~/.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"
]
}
}
}Edit ~/.codex/config.toml (global) or .codex/config.toml (project-level):
[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"You can also add it quickly via 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-mcpAdd a new Server in the MCP console:
Name:
wechat-devtoolsType:
commandCommand:
uvx wechat-devtools-mcpEnvironment Variables: add
WECHAT_DEVTOOLS_CLIandWECHAT_PROJECT_PATHas above
On Windows, backslashes in paths need to be escaped (
\\).
If you use Claude Code to develop inside a mini program repository, you can create a project-level .mcp.json (automatically follows the repository and applies to collaborators).
Windows — .mcp.json at the repository root:
{
"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 at the repository root:
{
"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"
}
}
}
}Three key differences on macOS:
commandmust use the absolute path/opt/homebrew/bin/uvx(Claude Code'sPATHdoes not include Homebrew when spawning child processes)
env.PATHmust be explicitly injected (especially needed when also configuringnpx-based MCPs such as cloudbase / chrome-devtools, otherwisenpx's#!/usr/bin/env nodecannot find Node)
NODE_PATHis recommended to be explicitly specified as a fallback when starting as a daemon
When configuring multiple MCPs at once (cloudbase / chrome-devtools, etc.), handle the
commandabsolute path andenv.PATHfor each server in the same pattern.
Trae v1.3.0+ supports MCP. AI panel → Settings icon in the top right → MCP → Add → Manual configuration, paste the JSON below and save.
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"
}
}
}
}You can also edit the config file directly:
Windows:
%APPDATA%\Trae\User\globalStorage\mcp.jsonmacOS:
~/Library/Application Support/Trae/User/globalStorage/mcp.json
[!IMPORTANT] You must select the 「Builder with MCP」 agent in the chat box; regular agents do not call MCP tools. It is also recommended to install the wechat-devtools Skill (Step 5) so the AI calls tools in SOP order.
Step 5 — Install the Skill (Required)
[!IMPORTANT] This MCP must be used together with the wechat-devtools Skill. The Skill contains all the SOP workflows, parameter quick references, and troubleshooting guides the AI needs to operate mini programs. Without the Skill installed, the AI can only call bare APIs and cannot automatically execute standardized testing and debugging workflows.
Option 1: npx skills add (Claude Code users)
npx -y skills add WaterTian/wechat-devtools-mcp/.agents/skills/wechat-devtoolsThis pulls it into ~/.claude/skills/, and Claude Code loads it automatically.
Option 2: Manually place it in .agents/skills/ (clients that load from .agents/skills/, such as Trae)
Run this in the mini program project root:
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-tmpThe resulting directory structure:
your-project/
└── .agents/skills/
└── wechat-devtools/
├── SKILL.md # 主指令文件(SOP + 能力映射 + 红线规则)
└── references/
└── tool_reference.md # 7 个聚合 API 完整参数参考[!TIP] Trae users: make sure the Settings → Skills & Commands → Enable .agents skills directory toggle is on (on by default). After saving, refresh and you will see
wechat-devtoolsunder the "Skills → Project" tab.
Related MCP server: Wechat Devtools MCP
🛠️ Toolbox Overview
The MCP Server provides 7 aggregated tools covering the full mini program lifecycle:
Tool | Function | Supported actions |
| IDE lifecycle management |
|
| Build and publish |
|
| Automated interaction |
|
| Runtime log collection |
|
| UI screenshots (long image stitching) | — |
| Navigate to pages and collect CDP logs | — |
| Project file reading |
|
For cloud functions and cloud database management, use CloudBase MCP (
manageFunctions/readNoSqlDatabaseContent, etc.), which is more complete and has no IDE dependency.wechat_cloudhas been disabled since v0.9.5.
🧠 Skill Content Details
The Skill lets the AI automatically match and execute standardized operation workflows after receiving natural language instructions:
What you say | What the AI executes |
"Check all pages for errors" | SOP D — Full-page inspection |
"Click the login button and take a screenshot" | SOP B — UI debugging |
"The page is blank, help me troubleshoot" | SOP C — Exception troubleshooting |
"Mock the payment API and test the payment flow" | SOP E — Mock integration testing |
"Test the detail page, what are the parameter names?" | SOP G — Sub-page testing |
"Compare whether points are consistent across pages" | SOP I — Cross-page data validation |
The Skill includes
9 SOP workflows — initialization, UI debugging, exception troubleshooting, full-page inspection, Mock integration testing, network debugging and UI adaptation, sub-page testing, cross-page data validation, parallel data comparison
Capability mapping dictionary — quick index of 7 aggregated tools × all actions
CDP progressive troubleshooting strategy — two stages: concise → full, to control token consumption
Complete parameter reference — required/optional parameters, return examples, and common templates for each action
Troubleshooting manual — common error codes and how to fix them
See Step 5 — Install the Skill for installation instructions
💡 Environment Variables
Variable | Description | Default | Required |
| WeChat DevTools CLI path | — | Yes |
| Default mini program project absolute path | — | Yes |
| CLI command timeout (seconds) |
| No |
| Node.js executable path |
| No |
❓ FAQ
Most common cause: the WeChat DevTools "Service Port" is not enabled.
Go to Settings → Security → Service Port and turn it on. Once enabled, the AI can reconnect without restarting the IDE.
If you opened DevTools manually, it may not be listening on the debug port. Close DevTools and let the AI run wechat_ide(action='open', cdp_enabled=True) to start it in debug mode.
The MCP service in the editor is still running. See the upgrade note under Step 1 — you need to terminate the process before upgrading.
An older version installed via pip install may take precedence. Run pip uninstall wechat-devtools-mcp to remove the old version, then confirm the mcp_version field is the latest via wechat_ide(action='status').
Make sure WECHAT_DEVTOOLS_CLI in the editor configuration's env is set to an absolute path:
Windows: use double backslashes (e.g.
C:\\...\\cli.bat)macOS: standard path
/Applications/wechatwebdevtools.app/Contents/MacOS/cli, no need to escape slashes
When GUI clients (such as Claude Desktop) start MCP, PATH may not include /opt/homebrew/bin. Since MCP v0.9.6, the Homebrew standard path is attempted automatically; if it still fails, set it explicitly in env:
"NODE_PATH": "/opt/homebrew/bin/node"📋 Version History
Version | Description |
0.9.15 | Adapt to DevTools 2.x (Electron) + fix long-standing CDP collection failure: DevTools 2.x switched to Electron (1.06.x Stable still uses NW.js, dual-track compatible, no replacement). macOS startup path auto-detects runtime based on presence of |
0.9.14 | File read path fix + parameter invalidation fix: |
0.9.13 |
|
0.9.12 | Handshake response package version + dependency upper bound: Under mcp 2.x, |
0.9.11 | Compatible with mcp 2.0.0: Official MCP Python SDK 2.0 (released 2026-07-28) removed |
0.9.10 | Fix page_path silent failure: screenshot.js verifies page path match after navigation; returns explicit error when |
0.9.9 | Fix screenshot causing mini-program restart: screenshot.js changes navigation for non-TabBar pages from |
0.9.8 | Fix automator connection stability: daemon.js |
0.9.7 | Fix daemon orphan process residue: daemon.js adds parent process watchdog, checks liveness every 5 seconds with |
0.9.6 | macOS adaptation: |
0.9.5 | Fix latent bug where compile health check permanently failed (ui_debug.js has no |
0.9.4 | Fix switchTab navigation not taking effect (switched to |
Version | Description |
0.9.3 | status adds |
0.9.2 | Fix navigate timeout after compile: daemon connection health check adds 3s timeout protection; automatically invalidates old cached connections and reconnects after compile; navigate currentPage polling adds 2s independent timeout per call; distinguishes HEALTH_CHECK_TIMEOUT and CONNECTION_ERROR error codes |
0.9.1 | Fix AttributeError crash when cdp_enabled=true; add WXML runtime error collection (CDP automatically captures warnings such as template not found after compile) |
0.9.0 | Persistent Node daemon architecture: single daemon process stays resident, NDJSON protocol communication, WS connections reused by port; single daemon.bundle.js replaces 8 independent bundles; tool call latency reduced from 500ms+ to ~3ms; daemon automatically rebuilds connections after compile with zero disconnects |
0.8.0 | Automatically reconnect automator after compile; navigate automatically detects TabBar pages and uses switchTab; screenshot adds full_page/scroll_top/page_path parameters and viewport screenshot mode; page_data adds expected_path polling to prevent stale data; long image stitching dynamic step size fixes content gaps; node_bridge unified connection disconnect retry + 500ms call interval; start port verification increased to 20 times |
0.7.0 | navigate variable scope fix (currentPageTimeout); evaluate supports declaration statements (const/let/var fallback); call_method returns current page path; automator start port polling verification replaces blind waiting; SKILL.md adds efficiency principles, recovery levels, page navigation methods, 6 troubleshooting entries |
0.6.0 | navigate supports query parameters (reLaunch timeout fallback); CDP startup noise filtering (console.assert/__route__/ide:// noise reduction + WXML error protection); compile return value three-way classification + automator invalidation prompt; navigate currentPage polling retry; configurable timeout |
0.5.1 |
|
0.5.0 | Skill SOP comprehensive optimization: adds SOP I/J; adds AppID check and path validation; CDP noise filtering; screenshot stitching fuzzy matching fix |
0.4.1 | Screenshot long page stitching rewrite: fixed region detection, DPR adaptation, dynamic overlap calculation |
0.4.0 | CDP log enhancement, cloud function deployment automatic verification, navigate intelligent diagnostics, adds SOP G/H |
0.3.0 | Major refactor: 44 tools consolidated into 8 APIs; CDP log v2; adds SKILL.md knowledge base |
0.2.6 | README adds OpenAI Codex configuration instructions |
0.2.5 | Adds Kiro editor configuration instructions |
0.2.4 | Screenshot scroll stitching fix: |
0.2.3 | Package optimization: excludes |
0.2.2 | Node.js scripts changed to bundle-only mode |
0.2.1 | Version update and documentation improvements |
0.2.0 | navigate switched to CDP high-definition log collection |
0.1.9 | Fix UTF-8 encoding garbled text |
0.1.8 | Fix Windows Chinese path UnicodeDecodeError |
0.1.7 | Adds core/full toolset presets; adds MCP_DOC.md |
0.1.6 |
|
0.1.5 | Fix Windows stdio blocking issue |
0.1.4 | Adds CDP logs, screenshots, automation and other features |
0.1.3 | Initial version |
Reference Documentation
License
MIT
Available Tools
7 toolswechat_automatorA
小程序自动化交互与运行时查询。 支持 action: start(开启自动化), tap(点击), input(输入), element_info(元素信息), set_data(设置数据), call_method(调用方法), call_wx(调用wx API), mock_wx(Mock wx), evaluate(执行JS), page_stack(页面栈), page_data(页面数据), system_info(系统信息), storage(缓存)。 返回 JSON: {success, data, message, error_code?}。
Inputs: params (required). Returns: result
wechat_buildBIdempotent
构建、预览、上传小程序及 npm 管理。 支持 action: compile(编译检查), preview(预览), upload(上传), build_npm(构建NPM), cache_clean(清缓存)。 返回 JSON: {success, data, message, error_code?}。
Inputs: params (required). Returns: result
wechat_fileARead-onlyIdempotent
读取小程序项目文件和结构信息。 支持 action: project_info(项目完整信息), list_pages(页面列表), read_page(读取页面源码), read_file(读取单个文件)。 返回 JSON: {success, data, message, error_code?}。
Inputs: params (required). Returns: result
wechat_ideAIdempotent
微信开发者工具 IDE 生命周期管理。 支持 action: open(打开IDE/项目), login(扫码登录), is_login(检查登录), close(关闭项目), quit(退出IDE), status(环境诊断)。 返回 JSON: {success, data, message, error_code?}。
Inputs: params (required). Returns: result
wechat_inspectorARead-onlyIdempotent
采集小程序运行时日志和异常。 支持 action: console(automator端口采集console日志和JS异常), cdp(通过CDP协议采集WXML警告、渲染层报错、废弃API提示等底层日志)。 cdp action 需先以 cdp_enabled=true 打开项目,确保端口 9222 可用。 返回 JSON: {success, data: {logs, summary}, message}。
Inputs: params (required). Returns: result
wechat_screenshotARead-onlyIdempotent
实时捕获当前小程序模拟器的界面截图。 默认支持截取长图,自动滚动并拼接。 output_path 可选,留空则自动保存到项目目录下 screenshots/ 文件夹。 返回 JSON: {success, data: {path, width, height, segments}, message}。
Inputs: params (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
The tools are mostly distinct by domain: IDE lifecycle, build/upload, automation, logging, navigation, file reading, and screenshots each have a clear role. There is some overlap between wechat_inspector and wechat_navigate because both collect CDP logs, and wechat_navigate depends on wechat_automator being started, but the descriptions make the intended boundaries reasonably clear.
All tools use a consistent wechat_ prefix and snake_case style, which makes the set predictable. The suffixes are mostly domain nouns (ide, build, automator, inspector, file) with one verb-like name (navigate), a minor deviation from an otherwise stable pattern.
Seven tools is well-scoped for a WeChat DevTools MCP server. Each tool represents a meaningful capability group with sub-actions, avoiding both a fragmented one-action-per-tool surface and an oversized tool list.
The surface covers the main developer workflow: IDE lifecycle, project/file inspection, build/preview/upload, screenshots, automation, navigation, and log collection. Minor gaps exist, such as no explicit automator stop/teardown action and no targeted element screenshot, but core workflows are well covered.
Maintenance
Related MCP Connectors
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Official Duck Framework MCP server for AI-assisted development and project scaffolding.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects WeChat Mini Program tooling to MCP and automation workflows. Provides scripts for opening, previewing, and uploading projects, as well as automator smoke tests.1MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to control WeChat mini-programs running in WeChat Developer Tools through MCP tools. Provides automation capabilities for launching, navigating, querying, and interacting with pages and elements.611MIT
- -licenseNot gradedqualityNot gradedmaintenanceEnables AI agents to debug and control WeChat Mini Programs through WeChat DevTools, including direct automator operations and CLI-backed features like screenshots, logs, previews, and uploads.-
- AlicenseAqualityBmaintenanceEnables AI agents to control WeChat DevTools on Windows through the official CLI and mini program automation SDK, supporting project operations, simulator navigation, element interaction, screenshots, evaluation, and wx API calls.23MIT