Content
# Tool List
## Overview
MCP Server for WeChat Mini Programs, powered by FastMCP and [`miniprogram-automator`](https://www.npmjs.com/package/miniprogram-automator), automates WeChat DevTools. This server provides MCP tools for AI assistants to navigate, inspect, and operate mini program pages—similar to `playwright-mcp` but customized for the WeChat ecosystem.
## Prerequisites
- WeChat DevTools installed, supporting command-line access (`cli` / `cli.bat`)
- Node.js 18+ and `npm` installed locally
- A mini program project that can be opened in DevTools
## Quick Start (npm Package)
`@yfme/weapp-dev-mcp` is published on npm. Users can skip cloning the repository or running `node dist/index.js`.
### Using npx
```bash
npx -y @yfme/weapp-dev-mcp
```
### Install to Project/Global
```bash
npm install -g @yfme/weapp-dev-mcp
weapp-dev-mcp
```
Or as a project dependency:
```bash
npm install --save-dev @yfme/weapp-dev-mcp
npx weapp-dev-mcp
```
> Only for development within this repository, directly run `node dist/index.js`. For general users, follow the npm package instructions.
## MCP Client Integration
### Configuration
To use this server with Claude Desktop or other MCP clients, add the following to your configuration file:
```json
{
"mcpServers": {
"weapp-dev": {
"command": "npx",
"args": [
"-y",
"@yfme/weapp-dev-mcp"
],
"env": {
"WEAPP_WS_ENDPOINT": "ws://localhost:9420"
}
}
}
}
```
### Claude Code Auto-Approval Tool Permissions
When using Claude Code to call MCP tools, it triggers tool call permission requests. This might lose the MCP connection to WeChat DevTools. To avoid this:
Create `.claude/settings.local.json` in your project directory or add to an existing file:
```json
{
"permissions": {
"allow": [
"mcp__weapp-dev-mcp__mp_ensureConnection",
"mcp__weapp-dev-mcp__mp_navigate",
"mcp__weapp-dev-mcp__mp_screenshot",
"mcp__weapp-dev-mcp__mp_callWx",
"mcp__weapp-dev-mcp__mp_getLogs",
"mcp__weapp-dev-mcp__mp_currentPage",
"mcp__weapp-dev-mcp__mp_listProjects",
"mcp__weapp-dev-mcp__mp_setDefaultProject",
"mcp__weapp-dev-mcp__page_getElement",
"mcp__weapp-dev-mcp__page_getElements",
"mcp__weapp-dev-mcp__page_waitElement",
"mcp__weapp-dev-mcp__page_waitTimeout",
"mcp__weapp-dev-mcp__page_getData",
"mcp__weapp-dev-mcp__page_setData",
"mcp__weapp-dev-mcp__page_callMethod",
"mcp__weapp-dev-mcp__element_tap",
"mcp__weapp-dev-mcp__element_input",
"mcp__weapp-dev-mcp__element_callMethod",
"mcp__weapp-dev-mcp__element_getData",
"mcp__weapp-dev-mcp__element_setData",
"mcp__weapp-dev-mcp__element_getInnerElement",
"mcp__weapp-dev-mcp__element_getInnerElements",
"mcp__weapp-dev-mcp__element_getWxml",
"mcp__weapp-dev-mcp__element_getStyles",
"mcp__weapp-dev-mcp__element_scrollTo",
"mcp__weapp-dev-mcp__element_getAttributes",
"mcp__weapp-dev-mcp__element_getBoundingClientRect"
]
}
}
```
> **Note:** Tool names follow the format `mcp__<server-name>__<tool-name>`. Ensure the server name matches your MCP configuration.
### Launch WeChat DevTools
Before using the MCP server, start WeChat DevTools and enable WebSocket services.
💡 Before starting:
1. Open WeChat DevTools
2. Go to **Settings → Security Settings → Service Ports**
3. Enable **"HTTP Debugging"** and **"Automation Testing"**
**Launching via Command Line**
Launch WeChat DevTools with WebSocket services enabled:
**macOS/Linux:**
```bash
/Applications/wechatwebdevtools.app/Contents/MacOS/cli auto --project /path/to/your/project --auto-port 9420
```
**Windows:**
```cmd
"C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat" auto --project C:\path\to\your\project --auto-port 9420
```
Where:
- `--project` specifies the mini program project directory path
- `--auto-port` specifies the WebSocket service port (default 9420)
**⚠️ Warning**
Due to sandbox mechanisms, some clients may not allow MCP to access the CLI outside the project directory. This guide focuses on using WebSocket services.
### Environment Variable Configuration
Control automation tools' connection to WeChat DevTools via environment variables:
| Variable | Description |
| --- | --- |
| `WEAPP_WS_ENDPOINT` | **Recommended.** The running DevTools WebSocket endpoint. If set, the server uses `connect` mode instead of launching a new instance. Example: `ws://localhost:9420` |
| `WECHAT_DEVTOOLS_CLI_PATH` | WeChat DevTools CLI path (optional if the default path works). |
| `WEAPP_AUTOMATOR_MODE` | Force `launch` or `connect` mode. Defaults to `launch` unless `WEAPP_WS_ENDPOINT` is provided. |
| `WEAPP_DEVTOOLS_PORT` | Preferred port when launching DevTools (fallback to available ports). |
| `WEAPP_DEVTOOLS_TIMEOUT` | Launch timeout in milliseconds (default 30000). |
| `WEAPP_AUTO_ACCOUNT` | Passed to `--auto-account` for auto-login. |
| `WEAPP_DEVTOOLS_TICKET` | Passed to `--ticket` when launching. |
| `WEAPP_TRUST_PROJECT` | Set to `true` to include `--trust-project` when launching. |
| `WEAPP_DEVTOOLS_ARGS` | Additional CLI arguments when launching (space-separated). |
| `WEAPP_DEVTOOLS_CWD` | Working directory for the DevTools process. |
| `WEAPP_AUTOCLOSE` | Set to `true` to close the DevTools session after each tool call. |
| `WEAPP_AUTOLAUNCH` | Set to `true` to auto-detect and launch DevTools |
| `WEAPP_LAUNCH_TIMEOUT` | Launch timeout in milliseconds (default 45000) |
| `WEAPP_CONNECT_TIMEOUT` | Connection timeout in milliseconds (default 45000) |
| `WEAPP_PROJECT_PATH` | Mini program project path (optional) |
> **Note:** When launching DevTools (`launch` mode), the mini program project directory must be provided via MCP tool parameters: e.g., through `connection.projectPath` (e.g., via `mp_ensureConnection`). This value persists across calls.
Tool calls can override most of these defaults via the `connection` object.
## Available Tools
### Application Tools
- `mp_ensureConnection` – Ensure the automation session is ready; optionally force a reconnect or override connection settings
- `mp_navigate` – Navigate within the mini program, supporting `navigateTo`, `redirectTo`, `reLaunch`, `switchTab`, or `navigateBack`
- `mp_screenshot` – Capture a screenshot and return it (or save to disk)
- `mp_callWx` – Call WeChat mini program API methods (e.g., `wx.showToast`)
- `mp_getLogs` – Get mini program console logs, optionally clearing them
- `mp_currentPage` – Get current page information (path, query params, dimensions, scroll position), with `withData` returning page data
- `mp_listProjects` – List recent projects in WeChat DevTools for easy project directory selection
- `mp_setDefaultProject` – Set the default mini program project path for future connections
### Page Tools
- `page_getElement` – Get a page element by selector, returning element summary info (tagName, text, value, size, offset); set `withWxml: true` for full outerWxml
- `page_getElements` – Get an array of page elements by selector, returning each element's summary info; set `withWxml: true` for each element's full outerWxml
- `page_waitElement` – Wait for an element to appear on the page (⚠️ not for elements within custom components); **supports `[index=N]` syntax; add timeout and retry interval parameters**
- `page_waitTimeout` – Wait for a specified number of milliseconds
- `page_getData` – Get the current page's data object, specifying paths (e.g., **supports nested paths like `'user.name'`**)
- `page_setData` – Update the current page's data using `setData`; **add a `verify` option to check if data is updated successfully**
- `page_callMethod` – Call a method exposed on the current page instance
### Element Tools
- `element_tap` – Simulate a tap on a WXML element via CSS selector; **supports `[index=N]` syntax for selecting the Nth element; supports x/y offset clicks; enhanced stability: waits for the element to be interactive and verifies the page path after clicking**
- `element_input` – Input text into an element (for `input` and `textarea` components)
- `element_callMethod` – Call a custom component instance method
- `element_getData` – Get a custom component instance's render data
- `element_setData` – Set a custom component instance's render data
- `element_getInnerElement` – Get an element within an element (equivalent to `element.$(selector)`), returning element summary info; set `withWxml: true` for full outerWxml
- `element_getInnerElements` – Get an array of elements within an element (equivalent to `element.$$(selector)`), returning element summary info; set `withWxml: true` for each element's full outerWxml
- `element_getWxml` – Get an element's WXML (inner or outer)
- `element_getStyles` – Get an element's CSS style values, with `names` parameter for style names (e.g., `['color', 'fontSize']`)
- `element_scrollTo` – Scroll a `scroll-view` component to a specified position (x, y)
- `element_getAttributes` – Get an element's attribute values, with `names` parameter for attribute names (e.g., `['class', 'id', 'data-index']`)
- `element_getBoundingClientRect` – Get an element's bounding client rectangle info (left, top, width, height, right, bottom), considering CSS transforms (currently supports ID selectors, class selectors)
Each tool accepts an optional `connection` block to override environment defaults (project path, CLI path, WebSocket endpoint, etc.).
## Tips
### General Tips
- Before connecting, enable automation in WeChat DevTools (`Settings → Security Settings → Service Ports`)
- Recommended to call `mp_ensureConnection` first to verify the connection and view system/page details
- Use `WEAPP_AUTOCLOSE=true` for stateless, one-time interactions
- **Always use absolute paths** for navigation (starting with `/`): `/pages/mine/mine`
- Use `switchTab` for tabBar pages and `navigateTo` for regular pages
### Operating Custom Components
Two methods for operating custom components:
#### Method 1: Using `innerSelector` Parameter (Recommended)
Applicable to tools like `element_tap`, `element_input`, `element_getWxml`:
```json
{
"selector": "#my-component",
"innerSelector": ".inner-button"
}
```
- `selector`: Custom component selector
- `innerSelector`: Selector for the element within the component
#### Method 2: Using Inner Query Tools
Applicable to `element_getInnerElement` and `element_getInnerElements`:
```json
{
"selector": "#my-component",
"targetSelector": ".inner-button"
}
```
#### Limitations
- `page_waitElement` **does not support** elements within custom components. Use `page_waitTimeout` with element query tools for polling checks.
### AutoLaunch Feature
When `WEAPP_AUTOLAUNCH=true`, the MCP server can auto-detect and launch WeChat DevTools:
1. **Auto-detect port**: Check if port 9420 is occupied
2. **Launch if not occupied**: If the port is free, auto-call CLI to launch DevTools
3. **Project selection**:
- Use default project config if available
- List recent projects for selection if no default project
- Support inputting project number (e.g., `1`) or full path
#### Configuration Example
```json
{
"mcpServers": {
"weapp-dev": {
"command": "npx",
"args": ["-y", "weapp-dev-mcp"],
"env": {
"WEAPP_AUTOLAUNCH": "true",
"WEAPP_PROJECT_PATH": "D:\\path\\to\\your\\project"
}
}
}
}
```
#### Workflow
1. First connection detects `WEAPP_AUTOLAUNCH=true`
2. Checks port 9420 occupancy
3. Launches DevTools if not occupied (using `cli.bat auto --project <path> --auto-port 9420`)
4. Waits 45 seconds for DevTools to be ready
5. Establishes WebSocket connection
6. **Subsequent connections reuse the existing connection**
> **Tip**: After setting a default project with `mp_setDefaultProject`, the next connection won't require project selection again.
