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)
> Encapsulates the WeChat Developer Tools CLI as a [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) service, enabling AI in editors to directly call WeChat CLI commands and achieve a full-process closed loop of **development, testing, debugging, and automation** for mini programs.
<!-- mcp-name: io.github.WaterTian/wechat-devtools-mcp -->
> [!IMPORTANT]
> This project adopts a "**lean MCP + fat Skill**" architecture: **MCP Server provides 7 aggregated APIs, and the accompanying [wechat-devtools Skill](#-install-skill-must) provides SOP processes, parameter quick checks, and best practices. Both must be used together**, and without the Skill, AI cannot operate the mini program according to the correct process.
**Released to the official [MCP Registry](https://modelcontextprotocol.io/)**, supporting cross-platform 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 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]
> - View 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 WaterTian/wechat-devtools-mcp/.agents/skills/wechat-devtools
> ```
### Step 2 — Enable Developer Tools Service Port
> [!WARNING]
> The service port must be manually enabled; otherwise, AI will not be able to issue any instructions.
**Operation Path**: `Developer Tools` → `Settings` → `Security Settings` → `Service Port` → `Enable`
> 💡 You can verify whether the port is enabled using `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:
| 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` in the same way
> Backslashes in Windows paths need to be escaped (`\\`).
</details>
<details>
<summary><b>Claude Code Project-level <code>.mcp.json</code> (Recommended for development within the repository)</b></summary>
If you are using Claude Code to develop within 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 an absolute path `/opt/homebrew/bin/uvx` (Claude Code spawns subprocesses without Homebrew in PATH)
> - `env.PATH` must be explicitly injected (also necessary 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) simultaneously, 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 → Settings (top right) → 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 directly edit the configuration file:
- Windows: `%APPDATA%\Trae\User\globalStorage\mcp.json`
- macOS: `~/Library/Application Support/Trae/User/globalStorage/mcp.json`
> [!IMPORTANT]
> The chat box must select **'Builder with MCP'** intelligence, and ordinary intelligence does 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.
### Step 5 — Install Skill (Required)
> [!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 the mini program. 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 WaterTian/wechat-devtools-mcp/.agents/skills/wechat-devtools
```
Will be pulled to `~/.claude/skills/`, and Claude Code will automatically load.
**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/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
```
Directory structure after completion:
```
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 turned 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 to see the effect" | 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 for each action, return examples, and common templates
- **Troubleshooting manual** — Common error codes and repair methods
> Installation method see [Step 5 — Install Skill](#step-5--install-skill-must)
## 💡 Environment Variables
| Variable name | 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**, 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) upgrade prompt — need to terminate the process before upgrading.
</details>
<details>
<summary><b><code>uv tool install</code> still runs the old version?</b></summary>
Maybe the old version installed by `pip install` has higher priority. Run `pip uninstall wechat-devtools-mcp` to remove the 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 later 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.10** | **Fix page_path silent failure**: screenshot.js verifies page path after navigation, returns explicit error if missing `/index` suffix or page does not exist; node_bridge.py fixes daemon handler error message loss ([#5](https://github.com/WaterTian/wechat-devtools-mcp/issues/5))|
| **0.9.9** | **Fix screenshot causing mini program restart**: screenshot.js changes navigation method from `reLaunch` (destruction of all page stack) to `navigateTo` (non-destructive stack) for non-TabBar pages; fixes macOS environment screenshot issue ([#4](https://github.com/WaterTian/wechat-devtools-mcp/issues/4))|
| **0.9.8** | **Fix automator connection stability**: daemon.js health check changes to polling retry (5 times × 3s+1.5s); `_action_start` uses `_run_cli` to synchronously detect CLI return code; CLI failure is immediately sensed ([#3](https://github.com/WaterTian/wechat-devtools-mcp/issues/3))|
| **0.9.7** | **Fix daemon orphan process residue**: daemon.js adds parent process watchdog, every 5 seconds `process.kill(ppid, 0)` detects survival; automatically cleans up WS connection and exits after parent process is killed ([#2](https://github.com/WaterTian/wechat-devtools-mcp/issues/2))|
| **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 adds Homebrew/nvm candidate path; README adds macOS path example |
| **0.9.5** | **Fix compile health check permanent failure**: (ui_debug.js no `page_stack` action, v0.9.0 since `automator_verified` always reported false); compile degrades to fail for fatal patterns like `EACCES`/`EADDRINUSE`/`#initialize-error`; preview automatically resolves relative path + 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 captures exception and issues warning; `wechat_cloud` tool is disabled (use CloudBase MCP instead) |
| **0.9.4** | Fix switchTab jump failure (use `miniProgram.switchTab()` instead of `callWxMethod`); compile reconnect 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; prints version number to stderr at startup; README adds pip/uv version conflict troubleshooting guide |
| 0.9.2 | **Fix compile then navigate timeout**: daemon connection health check adds 3s timeout protection; compile automatically invalidates old cache connection and reconnects; navigate currentPage polling adds 2s independent timeout; distinguishes HEALTH\_CHECK\_TIMEOUT and CONNECTION\_ERROR error codes |
| 0.9.1 | Fix AttributeError crash when `cdp_enabled=true`; adds WXML runtime error collection (compile then CDP automatically captures template not found 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 drops from 500ms+ to ~3ms; compile then daemon automatically rebuilds connection to zero disconnection |
| 0.8.0 | compile then automatically reconnects 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 uniformly disconnects and retries + 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 grading, page jump methods, and 6 fault entries |
| 0.6.0 | navigate supports query parameters (reLaunch timeout fallback); CDP startup noise filtering (console.assert/\_\_route\_\_/ide:// denoising + 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 seconds CDP logs to detect startup phase fatal errors, returns failure 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 keep `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 Documents
- [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/#WaterTian/wechat-devtools-mcp&Date">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=WaterTian/wechat-devtools-mcp&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=WaterTian/wechat-devtools-mcp&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=WaterTian/wechat-devtools-mcp&type=Date" />
</picture>
</a>
## License
MIT
