Weapp Dev MCP

🚀 WeChat Mini-Program MCP Server

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

🚀 Quick Start

Prerequisites

• Installed WeChat Developer Tools with 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 published to npm. Ordinary users don't need to clone the repository or manually execute node dist/index.js. The following commands will directly download the executable version from npm.

Run Temporarily with npx (Recommended)

npx -y \
  -p @modelcontextprotocol/sdk@1.17.2 \
  -p fastmcp@3.23.0 \
  -p @yfme/weapp-dev-mcp \
  weapp-dev-mcp

• -y automatically confirms dependency installation.
• Explicitly pin @modelcontextprotocol/sdk@1.17.2 and fastmcp@3.23.0 via -p to avoid the "Server does not support completions" error thrown by the new SDK during startup.
• weapp-dev-mcp is the name of the CLI exported in the package.

Install to Project/Globally

npm install --save-dev \
  @modelcontextprotocol/sdk@1.17.2 \
  fastmcp@3.23.0 \
  @yfme/weapp-dev-mcp

npx weapp-dev-mcp

Or use npm install -g ... && weapp-dev-mcp. You also need to lock the versions of the SDK and fastmcp.

It is recommended to directly run node dist/index.js only when developing within this repository. General users should start the server using the npm package method described above.

💻 MCP Client Integration

Configuration

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

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

Start WeChat Developer Tools

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

💡 Before you start:

1. Open the WeChat Developer Tools.
2. Go to Settings → Security Settings → Service Port.
3. Enable "HTTP Debugging" and "Automated Testing".

Start with Command Line Use the command line to start the 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:

• The --project parameter specifies the path to the mini-program project directory (replace it with the actual project path).
• The --auto-port parameter specifies the WebSocket service port (default is 9420).

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

Environment Variable Configuration

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

Note: When starting the developer tools (launch mode), you must provide the mini-program project directory through the MCP tool parameters: provide it via connection.projectPath before performing operations (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.

Common Errors

• Server does not support completions (required for completion/complete) The new version of @modelcontextprotocol/sdk requires completions capabilities during startup, but the current version of weapp-dev-mcp has not implemented the relevant interfaces. You can immediately avoid this by explicitly installing @modelcontextprotocol/sdk@1.17.2 and fastmcp@3.23.0 as per the commands in the "Quick Start" section. Compatibility logic will be built into future versions.

🛠️ 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 (or save to disk).
• mp_callWx – Call WeChat mini-program API methods (e.g., wx.showToast).
• mp_getLogs – Get the mini-program console logs, optionally clear them after retrieval.

Page Tools

• page_getElement – Get a page element by selector.
• page_waitElement – Wait for an element to appear on the page (⚠️ Not applicable to elements inside custom components).
• page_waitTimeout – Wait for the specified number of milliseconds.
• page_getData – Get the data object of the current page, optionally specify a path.
• page_setData – Update the data of the current page using setData.
• page_callMethod – Call a method exposed on the current page instance.

Element Tools

• element_tap – Tap a WXML element by CSS selector.
• element_input – Input text into an element (applicable to input and textarea components).
• element_callMethod – Call a method of a custom component instance (requires an ID selector).
• element_getData – Get the rendering data of a custom component instance (requires an ID selector).
• element_setData – Set the rendering data of a custom component instance (requires an ID selector).
• element_getInnerElement – Get an element inside an element (equivalent to element.$(selector)).
• element_getInnerElements – Get an array of elements inside an element (equivalent to element.$$(selector)).
• element_getSize – Get the size (width and height) of an element.
• element_getWxml – Get the WXML of an element (internal or external).

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 the 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 (starting with /) when navigating: /pages/mine/mine.
• Use switchTab for tabBar pages and navigateTo for ordinary pages.

Operating Custom Components

🔴 Important: You must use an ID selector (e.g., #my-component) to locate custom components.

There are two methods when operating custom components:

Method 1: Use the innerSelector Parameter (Recommended)

Applicable to tools such as element_tap, element_input, element_getSize, element_getWxml:

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

• selector: The ID selector of the custom component.
• innerSelector: The selector of the element inside the component.

Method 2: Use the Element Inner Query Tools

Applicable to element_getInnerElement and element_getInnerElements:

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

Limitations

• page_waitElement is not applicable to elements inside custom components. Use page_waitTimeout in conjunction with element query tools for polling checks.
• Custom component operations (e.g., element_callMethod, element_getData, element_setData) require the component to have an id attribute.