Content
# Tool List
## Overview
Based on FastMCP server, through [`miniprogram-automator`](https://www.npmjs.com/package/miniprogram-automator) automate the WeChat developer tools. This server provides MCP tools that allow AI assistants to navigate, inspect, and operate mini-program pages - similar to `playwright-mcp`, but customized for the WeChat ecosystem.
## Prerequisites
- WeChat developer tools installed, supporting command line access (`cli` / `cli.bat`)
- Node.js 18+ and `npm` installed locally
- A mini-program project that can be opened in the developer tools
## Quick Start (npm package)
`@yfme/weapp-dev-mcp` has been released to npm. Ordinary users do not need to clone the repository or manually execute `node dist/index.js`.
### Run with 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
```
> It is only recommended to directly run `node dist/index.js` when developing in this repository. General users should follow the above npm package method to start.
## MCP Client Integration
### Configuration
To use this server with Claude Desktop or other MCP clients, add the following to the configuration file:
```json
{
"mcpServers": {
"weapp-dev": {
"command": "npx",
"args": [
"-y",
"@yfme/weapp-dev-mcp"
],
"env": {
"WEAPP_WS_ENDPOINT": "ws://localhost:9420"
}
}
}
}
```
### Claude Code Automatic Approval Tool Permissions
Since using Claude Code to call MCP tools will trigger tool call permission requests, it may lose the connection status between MCP and the WeChat developer tools. As obtaining console output heavily relies on the connection status, it may not be able to continuously obtain output logs. Therefore, it is recommended to manually add permissions:
Create a `.claude/settings.local.json` file in the project directory, or add the following content to the existing file to免确认 directly call the tool, or add the tools you allow to call without confirmation according to your needs:
```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_mockWxMethod",
"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_getElementByXpath",
"mcp__weapp-dev-mcp__page_getElementsByXpath",
"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:** The tool name format is `mcp__<server name>__<tool name>`, please ensure that the server name is consistent with the name in your MCP configuration.
### Launch WeChat Developer Tools
Before using the MCP server, you need to launch the WeChat developer tools and enable the WebSocket service.
💡 Before starting:
1. Open WeChat developer tools
2. Go to **Settings → Security Settings → Service Port**
3. Enable **"HTTP Debugging"** and **"Automated Testing"**
**Launch using command line**
Launch WeChat developer tools using the command line and automatically enable the WebSocket service:
**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` parameter specifies the mini-program project directory path (please replace with the actual project path)
- `--auto-port` parameter specifies the WebSocket service port (default 9420)
**⚠️ Warning**
Due to the sandbox mechanism, some clients do not allow MCP to access the CLI of WeChat developer tools outside the project directory, so only the use of WebSocket services is introduced here
### Environment Variable Configuration
Control how the automation tool connects to the WeChat developer tools through environment variables:
| Variable | Description |
| --- | --- |
| `WEAPP_WS_ENDPOINT` | **【Recommended】** The WebSocket endpoint of the developer tools that have been running. After setting, the server uses `connect` mode instead of launching a new instance. Example: `ws://localhost:9420` |
| `WECHAT_DEVTOOLS_CLI_PATH` | The CLI path of WeChat developer tools (optional if the default path is valid). |
| `WEAPP_AUTOMATOR_MODE` | Force use of `launch` or `connect` mode. Defaults to `launch` unless `WEAPP_WS_ENDPOINT` is provided. |
| `WEAPP_DEVTOOLS_PORT` | The preferred port when launching developer tools (fallback to available ports). |
| `WEAPP_DEVTOOLS_TIMEOUT` | Launch timeout (milliseconds, default 30000). |
| `WEAPP_AUTO_ACCOUNT` | Pass `--auto-account` for automatic login. |
| `WEAPP_DEVTOOLS_TICKET` | Pass `--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` | The working directory passed to the developer tools process. |
| `WEAPP_AUTOCLOSE` | Set to `true` to close the developer tools session after each tool call. |
| `WEAPP_AUTOLAUNCH` | Set to `true` to automatically detect and launch developer tools |
| `WEAPP_LAUNCH_TIMEOUT` | Launch timeout (milliseconds, default 45000) |
| `WEAPP_CONNECT_TIMEOUT` | Connection timeout (milliseconds, default 45000) |
| `WEAPP_PROJECT_PATH` | Mini-program project path (optional) |
> **Note:** When launching developer tools (`launch` mode), you must provide the mini-program project directory through MCP tool parameters: provide it through `connection.projectPath` before executing the operation (e.g., through `mp_ensureConnection`). Once established, this value will be persisted in subsequent calls.
Tool calls can override most of these default values through the `connection` object.
## Available Tools
### Application Tools
- `mp_ensureConnection` – Ensure the automation session is ready; optionally force reconnection 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_mockWxMethod` – Limited mock `wx` method capabilities; currently supports `method: "request"`, set `wx.request` rules through `action: "mock"`, and restore the original method through `action: "restore"`
- `mp_getLogs` – Get mini-program console logs, optionally clearing them after retrieval
- `mp_currentPage` – Get the current page information (path, query parameters, size, scroll position), with `withData` returning page data
- `mp_listProjects` – List recent projects in WeChat developer tools for easy project directory selection
- `mp_setDefaultProject` – Set the default mini-program project path, automatically using it for the next connection
### Page Tools
- `page_getElement` – Get page elements through selectors, returning element summary information (tagName, text, value, size, offset); set `withWxml: true` to return complete outerWxml; **supports [index=N] syntax to select the Nth element**
- `page_getElements` – Get an array of page elements through selectors, returning each element's summary information; set `withWxml: true` to return each element's complete outerWxml; **supports [index=N] syntax**
- `page_getElementByXpath` – Get the first matching element through XPath, suitable for locating by text, attributes, hierarchy, ancestor/following, etc.; set `withWxml: true` to return complete outerWxml
- `page_getElementsByXpath` – Get an array of matching elements through XPath, returning each element's summary information; set `withWxml: true` to return each element's complete outerWxml
- `page_waitElement` – Wait for an element to appear on the page (⚠️ not applicable to 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 a path ( **supports nested paths like 'user.name'** )
- `page_setData` – Update the current page's data using `setData`; **add a verify option to verify if the data is actually updated successfully**
- `page_callMethod` – Call a method exposed on the current page instance
### Element Tools
- `element_tap` – Simulate a click on a WXML element through CSS selectors; **supports [index=N] syntax to select the Nth element; supports x/y coordinate offset click; enhanced stability: wait for the element to be interactive, automatically verify if the page path changes after clicking**
- `element_input` – Input text into an element (applicable to `input` and `textarea` components)
- `element_callMethod` – Call a custom component instance method
- `element_getData` – Get a custom component instance's rendering data
- `element_setData` – Set a custom component instance's rendering data
- `element_getInnerElement` – Get an element within an element (equivalent to `element.$(selector)`), returning element summary information; set `withWxml: true` to return complete outerWxml
- `element_getInnerElements` – Get an array of elements within an element (equivalent to `element.$$(selector)`), returning element summary information; set `withWxml: true` to return each element's complete outerWxml
- `element_getWxml` – Get an element's WXML (internal or external)
- `element_getStyles` – Get an element's CSS style values, with the names parameter being an array of 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 the names parameter being an array of attribute names (e.g., `['class', 'id', 'data-index']`)
- `element_getBoundingClientRect` – Get an element's bounding rectangle information relative to the viewport (left, top, width, height, right, bottom), considering CSS transform transformations (currently only supports ID selectors, class selectors)
Each tool accepts an optional `connection` block to override environment default values (project path, CLI path, WebSocket endpoint, etc.).
### Mock Network Requests
`mp_mockWxMethod` only exposes limited secure `mockWxMethod` capabilities, currently used to mock `wx.request`. The same tool supports setting and restoring:
```json
{
"action": "mock",
"method": "request",
"requestRules": [
{
"url": "/api/user",
"match": "contains",
"method": "GET",
"statusCode": 200,
"data": {
"id": 1,
"name": "test"
}
}
]
}
```
`match` supports `contains`, `exact`, `regex`. Requests hitting the rule will return a configured successful response; requests not hitting the rule will pass through the original `wx.request`. To restore:
```json
{
"action": "restore",
"method": "request"
}
```
## Usage Tips
### General Tips
- Before connecting, enable automation in WeChat developer tools (`Settings → Security Settings → Service Port`)
- It is 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** when navigating: `/pages/mine/mine`
- Use `switchTab` for tabBar pages, and `navigateTo` for ordinary pages
### Operating Custom Components
When operating custom components, there are two methods:
#### 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 elements within the component
#### Method 2: Using element query tools
Applicable to `element_getInnerElement` and `element_getInnerElements`:
```json
{
"selector": "#my-component",
"targetSelector": ".inner-button"
}
```
#### Limitation Description
- `page_waitElement` **not applicable to** elements within custom components. Please use `page_waitTimeout` with element query tools for polling checks.
### AutoLaunch
When configuring `WEAPP_AUTOLAUNCH=true`, the MCP server can automatically detect and launch WeChat developer tools:
1. **Automatically detect port**: Detect if port 9420 has a service running
2. **Launch if no service**: If the port is not occupied, automatically call CLI to launch developer tools
3. **Project selection**:
- If there is a default project configuration, automatically use it
- If there is no default project, automatically list recent projects for selection
- 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. Detect `WEAPP_AUTOLAUNCH=true` at the first connection
2. Check if port 9420 has a service
3. Automatically launch developer tools if no service (using `cli.bat auto --project <path> --auto-port 9420`)
4. Wait 45 seconds for developer tools to be ready
5. Establish WebSocket connection
6. **Subsequent connections automatically reuse the existing connection**
> **Tip**: Use `mp_setDefaultProject` to set the default project, and the next connection will not need to select the project again.
