Content
# Tool List
[](https://pypi.org/project/wechat-devtools-mcp/)
[](https://modelcontextprotocol.io/docs/concepts/mcp-registry)
[](https://opensource.org/licenses/MIT)
[](./README_EN.md)
> This project encapsulates the WeChat Developer Tools CLI as an MCP (Model Context Protocol) service, allowing AI in editors to directly call WeChat CLI commands and achieve a full-cycle closed loop of **development, testing, debugging, and automation** for mini programs.
<!-- mcp-name: io.github.XXXWANG/wechat-devtools-mcp -->
> [!IMPORTANT]
> This project adopts a "**lean MCP + fat Skill**" architecture: **MCP Server provides 8 aggregated APIs, and the accompanying [wechat-devtools Skill](#-install-skill-mandatory) provides SOP processes, parameter quick checks, and best practices. The two must be used together**, and without the Skill, AI will not be able to operate the mini program according to the correct process.
**Released to the official [MCP Registry](https://modelcontextprotocol.io/)**, supporting cross-platform (Windows / macOS) one-click installation.
---
> **🌐 [English Documentation →](./README_EN.md)**
---
## 🚀 Installation and Quick Start
### Step 1 — Install MCP Server
It is recommended to use [uv](https://github.com/astral-sh/uv), which can automatically handle Python dependencies and provide an isolated execution environment.
```bash
pip install uv # Install uv (skip if already installed)
uv tool install wechat-devtools-mcp --force # One-click install to the global isolated environment
```
> [!WARNING]
> If you have previously installed an old version using `pip install`, please uninstall it to avoid version conflicts:
> ```bash
> pip uninstall wechat-devtools-mcp
> ```
> The path of `pip install` (e.g., `Python313/Scripts/`) may take precedence over the path of `uv tool install` (e.g., `~/.local/bin/`), causing the actual running of the old version. You can confirm the current version through the `mcp_version` field returned by `wechat_ide(action='status')`.
> [!TIP]
> - Check the installed version:
> ```bash
> uv tool list | grep wechat # Offline confirmation of the installed version
> ```
> - Upgrade the tool: If the editor is running the MCP service, you need to terminate the process before upgrading:
> ```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 one-click upgrade:
> ```bash
> taskkill /F /IM "wechat-devtools-mcp*" 2>/dev/null; uv tool upgrade wechat-devtools-mcp && npx -y skills add XXXWANG/wechat-devtools-mcp/.agents/skills/wechat-devtools
> ```
### Step 2 — Enable Developer Tools Service Port
> [!WARNING]
> This must be enabled manually; otherwise, AI will not be able to send any instructions.
**Operation Path**: `Developer Tools` → `Settings` → `Security Settings` → `Service Port` → `Enable`
> 💡 You can verify whether the port is enabled through `wechat_ide(action='status')` - if it returns a connection failure, it means the service port is not enabled.
### Step 3 — Confirm Necessary Paths
Please obtain the following two absolute paths in advance and fill them into the editor configuration later:
| Path | Windows Example | macOS Example |
|------|-------------|-----------|
| WeChat Developer Tools CLI | `C:\Program Files (x86)\Tencent\WeChat Web Developer Tools\cli.bat` | `/Applications/wechatwebdevtools.app/Contents/MacOS/cli` |
| Mini Program Project Root Directory | `D:\MyProjects\mini-app` | `/Users/<you>/Projects/mini-app` |
> macOS users: No need to escape slashes (`/`) in JSON configuration; Windows users need to write `\` as `\\`.
### Step 4 — Editor Configuration
<details>
<summary><b>Claude Desktop / Antigravity</b></summary>
Modify `claude_desktop_config.json` or `mcp_config.json` (Antigravity):
```json
{
"mcpServers": {
"wechat-devtools": {
"command": "uvx",
"args": ["wechat-devtools-mcp"],
"env": {
"WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\WeChat Web Developer Tools\\cli.bat",
"WECHAT_PROJECT_PATH": "D:\\Your\\Project\\Path"
}
}
}
}
```
</details>
<details>
<summary><b>Kiro</b></summary>
Edit `~/.kiro/settings/mcp.json`:
```json
{
"mcpServers": {
"wechat-devtools": {
"command": "uvx",
"args": ["wechat-devtools-mcp"],
"env": {
"WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\WeChat Web Developer Tools\\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"
]
}
}
}
```
</details>
<details>
<summary><b>OpenAI Codex</b></summary>
Edit `~/.codex/config.toml` (global) or `.codex/config.toml` (project-level):
```toml
[mcp_servers.wechat-devtools]
command = "uvx"
args = ["wechat-devtools-mcp"]
[mcp_servers.wechat-devtools.env]
WECHAT_DEVTOOLS_CLI = "C:\\Program Files (x86)\\Tencent\\WeChat Web Developer Tools\\cli.bat"
WECHAT_PROJECT_PATH = "D:\\Your\\Project\\Path"
```
You can also add it quickly through CLI:
```bash
codex mcp add wechat-devtools \
--env WECHAT_DEVTOOLS_CLI="C:\\Program Files (x86)\\Tencent\\WeChat Web Developer Tools\\cli.bat" \
--env WECHAT_PROJECT_PATH="D:\\Your\\Project\\Path" \
-- uvx wechat-devtools-mcp
```
</details>
<details>
<summary><b>Cursor / VS Code (MCP Plugin)</b></summary>
Add a new Server in the MCP console:
- **Name**: `wechat-devtools`
- **Type**: `command`
- **Command**: `uvx wechat-devtools-mcp`
- **Environment Variables**: Add `WECHAT_DEVTOOLS_CLI` and `WECHAT_PROJECT_PATH` as above
> In Windows, backslashes in paths need to be escaped (`\\`).
</details>
<details>
<summary><b>Claude Code Project-level <code>.mcp.json</code> (Recommended for development in the repository)</b></summary>
If you are developing with Claude Code in a mini program repository, you can create a project-level `.mcp.json` (automatically follows the repository and takes effect for collaborators).
**Windows** — Repository root directory `.mcp.json`:
```json
{
"mcpServers": {
"wechat-devtools": {
"command": "uvx",
"args": ["wechat-devtools-mcp"],
"env": {
"WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\WeChat Web Developer Tools\\cli.bat",
"WECHAT_PROJECT_PATH": "D:\\Your\\Project\\Path"
}
}
}
}
```
**macOS** — Repository root directory `.mcp.json`:
```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 has three key differences:
> - `command` must use the absolute path `/opt/homebrew/bin/uvx` (Claude Code spawns subprocesses without Homebrew in PATH)
> - `env.PATH` must be explicitly injected (especially when configuring multiple MCPs like cloudbase / chrome-devtools)
> - `NODE_PATH` is recommended to be explicitly specified as a double insurance when starting as a daemon
> When configuring multiple MCPs (e.g., cloudbase / chrome-devtools), each server handles `command` absolute paths and `env.PATH` in the same way.
</details>
<details>
<summary><b>Trae IDE (Global <code>mcp.json</code>)</b></summary>
Trae v1.3.0+ supports MCP. **AI Panel → Top-right settings → MCP → Add → Manual configuration**, paste the JSON below and save.
**Windows**:
```json
{
"mcpServers": {
"wechat-devtools": {
"command": "uvx",
"args": ["wechat-devtools-mcp"],
"env": {
"WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\WeChat Web Developer Tools\\cli.bat",
"WECHAT_PROJECT_PATH": "D:\\Your\\Project\\Path"
}
}
}
}
```
**macOS**:
```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"
}
}
}
}
```
You can also edit the configuration file directly:
- Windows: `%APPDATA%\Trae\User\globalStorage\mcp.json`
- macOS: `~/Library/Application Support/Trae/User/globalStorage/mcp.json`
> [!IMPORTANT]
> The chat box must select the **'Builder with MCP'** smart agent; ordinary smart agents do not call MCP tools. It is recommended to install the wechat-devtools Skill (Step 5) so that AI can call in the order of SOP.
</details>
### Step 5 — Install Skill (Mandatory)
> [!IMPORTANT]
> **This MCP must be used with the wechat-devtools Skill**. The Skill contains all the SOP processes, parameter quick checks, and troubleshooting guides required for AI to operate mini programs. Without the Skill, AI can only call bare APIs and cannot automatically execute standardized testing and debugging processes.
**Method 1: `npx skills add` (Claude Code users)**
```bash
npx -y skills add XXXWANG/wechat-devtools-mcp/.agents/skills/wechat-devtools
```
Will be pulled to `~/.claude/skills/`, and Claude Code will load it automatically.
**Method 2: Manually place it in `.agents/skills/` (Clients based on `.agents/skills/` loading, such as Trae)**
Execute in the mini program project root directory:
```bash
git clone --depth 1 https://github.com/XXXWANG/wechat-devtools-mcp.git .wdm-tmp
mkdir -p .agents/skills
cp -r .wdm-tmp/.agents/skills/wechat-devtools .agents/skills/
rm -rf .wdm-tmp
```
Completed directory structure:
```
your-project/
└── .agents/skills/
└── wechat-devtools/
├── SKILL.md # Main instruction file (SOP + capability mapping + red line rules)
└── references/
└── tool_reference.md # Complete parameter reference for 7 aggregated APIs
```
> [!TIP]
> **Trae users**: Confirm **Settings → Skills and Commands → Enable .agents skills directory** switch is on (default on), save and refresh to see `wechat-devtools` in the **Skills → Project** tab.
## 🛠️ Tool Box Overview
MCP Server provides **7 aggregated tools**, covering the full lifecycle of mini programs:
| Tool | Function | Supported actions |
|------|------|--------------|
| `wechat_ide` | IDE lifecycle management | `open` `login` `is_login` `close` `quit` `status` |
| `wechat_build` | Build and publish | `compile` `preview` `upload` `build_npm` `cache_clean` |
| `wechat_automator` | Automated interaction | `start` `tap` `input` `element_info` `set_data` `call_method` `call_wx` `mock_wx` `evaluate` `page_stack` `page_data` `system_info` `storage` |
| `wechat_inspector` | Runtime log collection | `console` `cdp` |
| `wechat_screenshot` | Interface screenshot (long image stitching) | — |
| `wechat_navigate` | Jump to page and collect CDP logs | — |
| `wechat_file` | Project file reading | `project_info` `list_pages` `read_page` `read_file` |
> For cloud function and cloud database management, please use [CloudBase MCP](https://github.com/TencentCloudBase/CloudBase-AI-ToolKit) (`manageFunctions` / `readNoSqlDatabaseContent`, etc.), which has more complete functions and does not depend on IDE. `wechat_cloud` has been disabled since v0.9.5.
>
> For complete tool parameter instructions, please refer to **[MCP_DOC.md](./MCP_DOC.md)**
## 🧠 Skill Content Details
Skill allows AI to automatically match and execute standardized operation processes after receiving natural language instructions:
| What you say | AI execution process |
|---------|--------------|
| "Help me 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 payment interface, test payment process" | SOP E — Mock integration testing |
| "Test the details page, what is the parameter name" | SOP G — Sub-page testing |
| "Compare the points on each page to see if they are consistent" | SOP I — Cross-page data verification |
### Skill Includes
- **9 SOP processes** — Initialization, UI debugging, exception troubleshooting, full page inspection, mock integration testing, network debugging and UI adaptation, sub-page testing, cross-page data verification, and parallel data comparison
- **Capability mapping dictionary** — Quick index of 7 aggregated tools × all actions
- **CDP progressive troubleshooting strategy** — Concise → full two-stage, controlling Token consumption
- **Complete parameter reference** — Required/optional parameters, return examples, and common templates for each action
- **Troubleshooting manual** — Common error codes and repair methods
> Installation method see [Step 5 — Install Skill](#step-5--install-skill-must)
## 💡 Environment Variables
| Variable | Description | Default value | Required |
|--------|------|--------|------|
| `WECHAT_DEVTOOLS_CLI` | WeChat developer tool CLI path | — | **Yes** |
| `WECHAT_PROJECT_PATH` | Default mini program project absolute path | — | **Yes** |
| `WECHAT_CLI_TIMEOUT` | CLI command timeout (seconds) | `30` | No |
| `NODE_PATH` | Node.js execution file path | `node` | No |
## ❓ Frequently Asked Questions
<details>
<summary><b>Why does AI always report <code>CLI_TIMEOUT</code> error?</b></summary>
**Most common reason**: WeChat developer tool's "Service Port" is not enabled.
Go to `Settings` → `Security` → `Service Port` and enable it. After enabling, no need to restart IDE, AI can recover connection.
</details>
<details>
<summary><b><code>wechat_inspector</code> returns "CDP collection failed"</b></summary>
If you manually opened the developer tool, it may not be listening to the debugging port. **Please close the developer tool**, and let AI execute `wechat_ide(action='open', cdp_enabled=True)` to start in debug mode.
</details>
<details>
<summary><b><code>uv tool upgrade</code> prompts file occupied?</b></summary>
MCP service in the editor is still running. Refer to [Step 1](#step-1--install-mcp-server) for upgrade instructions — need to terminate the process before upgrading.
</details>
<details>
<summary><b><code>uv tool install</code> still runs old version?</b></summary>
Maybe old version installed by `pip install` has higher priority. Run `pip uninstall wechat-devtools-mcp` to remove old version, then confirm `mcp_version` field is the latest version through `wechat_ide(action='status')`.
</details>
<details>
<summary><b>AI cannot find WeChat CLI path?</b></summary>
Ensure `WECHAT_DEVTOOLS_CLI` is filled with absolute path in editor configuration `env`:
- **Windows**: Use double backslashes (e.g., `C:\\...\\cli.bat`)
- **macOS**: Standard path `/Applications/wechatwebdevtools.app/Contents/MacOS/cli`, no need to escape slashes
</details>
<details>
<summary><b>Node.js detection failed on macOS?</b></summary>
GUI client (e.g., Claude Desktop) may not include `/opt/homebrew/bin` in `PATH` when launching MCP. MCP v0.9.6 and above will automatically try Homebrew standard path; if still failed, explicitly set in `env`:
```json
"NODE_PATH": "/opt/homebrew/bin/node"
```
</details>
## 📋 Version History
| Version | Description |
|------|------|
| **0.9.6** | **macOS adaptation**: `cdp_enabled=true` mode cross-platform launch (NW.js main program `wechatdevtools` + `package.nw` entry + `pkill` cleanup); default CLI path returns by platform; Node.js detection complements Homebrew/nvm candidate paths; README adds macOS path example |
| **0.9.5** | **Fix compile health check permanent failure potential bug** (ui_debug.js no `page_stack` action, v0.9.0 and above `automator_verified` always reported false); compile to `EACCES`/`EADDRINUSE`/`#initialize-error` and other fatal patterns downgrade to fail, eliminating "false success publish old bundle"; preview automatically resolves relative paths + mtime freshness detection; `wechat_automator(action='start')` upgrades to TCP+WS dual verification + `retry_after_ms` precise waiting; compile detects `miniprogram_npm` expiration and issues warning; inspector short duration captures exception and issues warning; `wechat_cloud` tool disabled (use CloudBase MCP instead) |
| **0.9.4** | Fix switchTab jump ineffective (replace `callWxMethod` with `miniProgram.switchTab()`); compile post-reconnection stability (remove redundant process + 3s delay + WS health check); README 5 item agent friendliness improvement |
<details>
<summary>Expand v0.9.3 and earlier versions</summary>
| Version | Description |
|------|------|
| 0.9.3 | status adds `mcp_version` field for version confirmation; print version number to stderr at startup; README adds pip/uv version conflict troubleshooting guide |
| 0.9.2 | **Fix compile post-navigate timeout**: daemon connection health check adds 3s timeout protection; compile automatically invalidates old cache connection and reconnects; navigate currentPage polling each call adds 2s independent timeout; distinguish HEALTH\_CHECK\_TIMEOUT and CONNECTION\_ERROR error codes |
| 0.9.1 | Fix AttributeError crash when `cdp_enabled=true`; add WXML runtime error collection (compile post-CDP automatically captures template not found and other warnings) |
| 0.9.0 | **Persistent Node daemon architecture**: single daemon process resident, NDJSON protocol communication, WS connection reuse by port; single daemon.bundle.js replaces 8 independent bundles; tool call delay from 500ms+ to ~3ms; compile post-daemon automatically rebuilds connection zero disconnection |
| 0.8.0 | Compile post-automatic reconnection to automator; navigate automatically identifies TabBar page to switchTab; screenshot adds full\_page/scroll\_top/page\_path parameters and viewport screenshot mode; page\_data adds expected\_path polling to prevent old data; long image stitching dynamic step length fixes content gap; node\_bridge unified connection disconnection retry + 500ms call interval; start port verification increases 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 wait; SKILL.md adds efficiency principles, recovery level, page jump method, and 6 fault 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 classification + automator failure prompt; navigate currentPage polling retry; timeout configurable |
| 0.5.1 | `wechat_ide(action='open')` adds CDP startup health check: automatically collects 5-second CDP logs to detect startup phase fatal errors, returns failure directly if error occurs |
| 0.5.0 | Skill SOP comprehensive optimization: adds SOP I/J; adds AppID check and path verification; CDP noise filtering; screenshot stitching fuzzy matching fix |
| 0.4.1 | Screenshot long page stitching rewrite: fixed area detection, DPR adaptive, dynamic overlap calculation |
| 0.4.0 | CDP log enhancement, cloud function deployment automatic verification, navigate intelligent diagnosis, adds SOP G/H |
| 0.3.0 | **Major refactoring**: 44 tools aggregated 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 scrolling stitching fix: `sharp` → `jimp` |
| 0.2.3 | Release package optimization: exclude `scripts/` source code, only retain `dist/` build product |
| 0.2.2 | Node.js script changes to bundle-only mode |
| 0.2.1 | Version update and documentation improvement |
| 0.2.0 | navigate changes to CDP high-definition log collection |
| 0.1.9 | Fix UTF-8 encoding garbled |
| 0.1.8 | Fix Windows Chinese path UnicodeDecodeError |
| 0.1.7 | Adds core/full toolset presets; adds MCP_DOC.md |
| 0.1.6 | `wechat_open(cdp_enabled=true)` automatically kills existing process |
| 0.1.5 | Fix Windows stdio blocking issue |
| 0.1.4 | Adds CDP log, screenshot, automation, and other features |
| 0.1.3 | Initial version |
</details>
## Reference Documentation
- [WeChat Developer Tool CLI Official Documentation](https://developers.weixin.qq.com/miniprogram/dev/devtools/cli.html)
- [Mini Program Automation SDK](https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/quick-start.html)
<a href="https://star-history.com/#XXXWANG/wechat-devtools-mcp&Date">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=XXXWANG/wechat-devtools-mcp&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=XXXWANG/wechat-devtools-mcp&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=XXXWANG/wechat-devtools-mcp&type=Date" />
</picture>
</a>
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available