WeChat Mini Program MCP Server

A FastMCP-based server that automates WeChat Developer Tools via miniprogram-automator. This server provides MCP tools that allow AI assistants to navigate, inspect, and manipulate mini program pages—similar to playwright-mcp, but tailored for the WeChat ecosystem.

Prerequisites

• WeChat Developer Tools installed with command-line access (cli / cli.bat) enabled.

• Node.js 18+ and npm installed locally.

• A mini program project that can be opened in the Developer Tools.

Related MCP server: weapp-agent-mcp

Quick Start (npm package)

@yfme/weapp-dev-mcp has been published to npm. Regular users do not need to clone the repository or manually execute node dist/index.js.

Run with npx

npx -y @yfme/weapp-dev-mcp

Install globally or in a project

npm install -g @yfme/weapp-dev-mcp
weapp-dev-mcp

Or as a project dependency:

npm install --save-dev @yfme/weapp-dev-mcp
npx weapp-dev-mcp

Only when developing within this repository is it recommended to run node dist/index.js directly. General users should start via the npm package method above.

MCP Client Integration

Configuration

To use this server in Claude Desktop or other MCP clients, add the following to your configuration file:

{
  "mcpServers": {
    "weapp-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@yfme/weapp-dev-mcp"
      ],
      "env": {
        "WEAPP_WS_ENDPOINT": "ws://localhost:9420"
      }
    }
  }
}

Claude Code Auto-Approval for Tools

Since calling MCP tools via Claude Code triggers tool permission requests, the connection state between the MCP and WeChat Developer Tools might be lost. Because retrieving console output is highly dependent on the connection state, it may be impossible to obtain output logs coherently. Therefore, it is recommended to add permissions manually:

Create a .claude/settings.local.json file in your project directory, or add the following content to an existing file to allow direct tool calls without confirmation, or add the specific tools you wish to allow without confirmation as needed:

{
  "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: The tool name format is mcp__<server_name>__<tool_name>. Please ensure the server name matches the one in your MCP configuration.

Starting WeChat Developer Tools

Before using the MCP server, you must start the WeChat Developer Tools and enable the WebSocket service.

💡 Before you begin:

1. Open WeChat Developer Tools.

2. Go to Settings → Security Settings → Service Port.

3. Enable "HTTP Debugging" and "Automation Testing".

Start via Command Line

Use the command line to start WeChat Developer Tools and automatically enable the WebSocket service:

macOS/Linux:

/Applications/wechatwebdevtools.app/Contents/MacOS/cli auto --project /path/to/your/project --auto-port 9420

Windows:

"C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat" auto --project C:\path\to\your\project --auto-port 9420

Where:

• --project specifies the path to the mini program project directory (please replace with the actual project path).

• --auto-port specifies the WebSocket service port (default is 9420).

⚠️ Warning Due to sandbox mechanisms, some clients do not allow MCP to access the WeChat Developer Tools CLI outside of the project directory, so only the WebSocket service method is introduced here.

Environment Variable Configuration

Control how the automation tool connects to WeChat Developer Tools via environment variables:

Note: When launching Developer Tools (launch mode), you must provide the mini program project directory via MCP tool parameters: provide it via connection.projectPath before performing operations (e.g., via mp_ensureConnection). Once established, this value will persist in subsequent calls.

Tool calls can override most of these defaults via the connection object.

Available Tools

Application Tools

• mp_ensureConnection – Ensures the automation session is ready; optionally force reconnect or override connection settings.

• mp_navigate – Navigate within the mini program; supports 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 – Retrieve mini program console logs, optionally clearing them after retrieval.

• mp_currentPage – Get current page information (path, query parameters, dimensions, scroll position); returns page data if withData is true.

• mp_listProjects – List recent projects in WeChat Developer Tools for easy selection of project directories.

• mp_setDefaultProject – Set the default mini program project path; once set, the next connection will automatically use this project.

Page Tools

• page_getElement – Get a page element via selector, returns element summary (tagName, text, value, size, offset); set withWxml: true to additionally return the full outerWxml; supports [index=N] syntax to select the Nth element.

• page_getElements – Get an array of page elements via selector, returns summary for each; set withWxml: true to additionally return the full outerWxml for each; supports [index=N] syntax.

• page_waitElement – Wait for an element to appear on the page (⚠️ not applicable to elements inside custom components); supports [index=N] syntax; adds timeout and retry interval parameters.

• page_waitTimeout – Wait for a specified number of milliseconds.

• page_getData – Get the data object of the current page, can specify a path (supports nested paths like 'user.name').

• page_setData – Update the current page's data using setData; adds a verify option to confirm if data was actually 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 to select the Nth element; supports x/y coordinate offset tapping; enhanced stability: waits for element interactivity, automatically verifies if the page path changed after tapping.

• element_input – Input text into an element (applicable to input and textarea components).

• element_callMethod – Call a method on a custom component instance.

• element_getData – Get rendering data of a custom component instance.

• element_setData – Set rendering data of a custom component instance.

• element_getInnerElement – Get an element inside an element (equivalent to element.$(selector)), returns element summary; set withWxml: true to additionally return the full outerWxml.

• element_getInnerElements – Get an array of elements inside an element (equivalent to element.$$(selector)), returns element summary; set withWxml: true to additionally return the full outerWxml for each.

• element_getWxml – Get element WXML (inner or outer).

• element_getStyles – Get CSS style values of an element, names parameter is 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 attribute values of an element, names parameter is an array of attribute names (e.g., ['class', 'id', 'data-index']).

• element_getBoundingClientRect – Get the bounding rectangle information of an element relative to the viewport (left, top, width, height, right, bottom), considering CSS transforms (currently only supports ID and class selectors).

Each tool accepts an optional connection block to override environment defaults (project path, CLI path, WebSocket endpoint, etc.).

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.

• Using WEAPP_AUTOCLOSE=true is suitable for stateless, one-off interactions.

• Always use absolute paths when navigating (starting with /): /pages/mine/mine.

• Use switchTab for tabBar pages, and navigateTo for regular pages.

Operating Custom Components

There are two ways to operate custom components:

Method 1: Use the innerSelector parameter (Recommended)

Applicable to tools like element_tap, element_input, element_getWxml, etc.:

{
  "selector": "#my-component",
  "innerSelector": ".inner-button"
}

• selector: The selector for the custom component.

• innerSelector: The selector for the element inside the component.

Method 2: Use element inner query tools

Applicable to element_getInnerElement and element_getInnerElements:

{
  "selector": "#my-component",
  "targetSelector": ".inner-button"
}

Limitations

• page_waitElement does not apply to elements inside custom components. Please use page_waitTimeout in conjunction with element query tools for polling checks.

AutoLaunch Feature

When WEAPP_AUTOLAUNCH=true is configured, the MCP server can automatically detect and launch WeChat Developer Tools:

1. Auto-detect port: Detects if a service is running on port 9420.

2. Launch if no service: If the port is not occupied, it automatically calls the CLI to launch the Developer Tools.

3. Project selection:

   • If a default project is configured, it is used automatically.

   • If no default project exists, it automatically lists recent projects for selection.

   • Supports entering a project number (e.g., 1) or the full path.

Configuration Example

{
  "mcpServers": {
    "weapp-dev": {
      "command": "npx",
      "args": ["-y", "weapp-dev-mcp"],
      "env": {
        "WEAPP_AUTOLAUNCH": "true",
        "WEAPP_PROJECT_PATH": "D:\\path\\to\\your\\project"
      }
    }
  }
}

Workflow

1. Upon first connection, WEAPP_AUTOLAUNCH=true is detected.

2. Checks if a service is running on port 9420.

3. If no service, automatically launches Developer Tools (using cli.bat auto --project <path> --auto-port 9420).

4. Waits 45 seconds for the Developer Tools to be ready.

5. Establishes a WebSocket connection.

6. Subsequent connections automatically reuse the existing connection.

Tip: After setting a default project using mp_setDefaultProject, you do not need to select the project again for the next connection.