# weapp-agent-mcp

This MCP server lets coding agents drive WeChat DevTools for Mini Program debugging, page interaction, and small regression checks.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 21
- Author: Chaixueyuan
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Chaixueyuan/weapp-agent-mcp
- Updated: 2026-07-01
- HTML: https://affpapa.org/en/nevibecode/mcp/weapp-agent-mcp

## What it does

weapp-agent-mcp exposes WeChat DevTools actions to an agent through MCP. It can capture screenshots and page state, navigate between routes, find elements, interact with them, and check visible UI conditions. Short test flows can run through `mp_runScenario`, with a Markdown result produced by `mp_generateScenarioReport`.

The server wraps `miniprogram-automator` and includes connection checks plus recovery tools such as `mp_healthCheck` and `mp_recoverConnection`. Stable `qa-*` selectors help keep page checks usable after UI changes. Screenshot handling is serial, so concurrent capture is outside its intended use; long flows are better split into shorter scenarios.

You need WeChat DevTools with automation and its service port enabled, Node.js 18+, `npm`, and a Mini Program project that DevTools can open. Without those DevTools settings, the MCP server cannot control the app.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `WEAPP_WS_ENDPOINT`, `WEAPP_AUTOMATOR_MODE`, `WEAPP_PROJECT_PATH`, `WECHAT_DEVTOOLS_CLI_PATH`, `WEAPP_DEVTOOLS_PORT`, `WEAPP_DEVTOOLS_TIMEOUT`, `WEAPP_AUTO_ACCOUNT`, `WEAPP_DEVTOOLS_TICKET`, `WEAPP_TRUST_PROJECT`, `WEAPP_DEVTOOLS_ARGS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env WEAPP_WS_ENDPOINT=<WEAPP_WS_ENDPOINT> --env WEAPP_AUTOMATOR_MODE=<WEAPP_AUTOMATOR_MODE> --env WEAPP_PROJECT_PATH=<WEAPP_PROJECT_PATH> --env WECHAT_DEVTOOLS_CLI_PATH=<WECHAT_DEVTOOLS_CLI_PATH> --env WEAPP_DEVTOOLS_PORT=<WEAPP_DEVTOOLS_PORT> --transport stdio weapp-agent-mcp -- npx -y @chaixueyuan/weapp-agent-mcp
```
Replace <…> with your own values. 10 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add weapp-agent-mcp --env WEAPP_WS_ENDPOINT=<WEAPP_WS_ENDPOINT> --env WEAPP_AUTOMATOR_MODE=<WEAPP_AUTOMATOR_MODE> --env WEAPP_PROJECT_PATH=<WEAPP_PROJECT_PATH> --env WECHAT_DEVTOOLS_CLI_PATH=<WECHAT_DEVTOOLS_CLI_PATH> --env WEAPP_DEVTOOLS_PORT=<WEAPP_DEVTOOLS_PORT> -- npx -y @chaixueyuan/weapp-agent-mcp
```
Replace <…> with your own values. 10 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "weapp-agent-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@chaixueyuan/weapp-agent-mcp"
            ],
            "env": {
                "WEAPP_WS_ENDPOINT": "<WEAPP_WS_ENDPOINT>",
                "WEAPP_AUTOMATOR_MODE": "<WEAPP_AUTOMATOR_MODE>",
                "WEAPP_PROJECT_PATH": "<WEAPP_PROJECT_PATH>",
                "WECHAT_DEVTOOLS_CLI_PATH": "<WECHAT_DEVTOOLS_CLI_PATH>",
                "WEAPP_DEVTOOLS_PORT": "<WEAPP_DEVTOOLS_PORT>"
            }
        }
    }
}
```
Replace <…> with your own values. 10 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "weapp-agent-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@chaixueyuan/weapp-agent-mcp"
            ],
            "env": {
                "WEAPP_WS_ENDPOINT": "<WEAPP_WS_ENDPOINT>",
                "WEAPP_AUTOMATOR_MODE": "<WEAPP_AUTOMATOR_MODE>",
                "WEAPP_PROJECT_PATH": "<WEAPP_PROJECT_PATH>",
                "WECHAT_DEVTOOLS_CLI_PATH": "<WECHAT_DEVTOOLS_CLI_PATH>",
                "WEAPP_DEVTOOLS_PORT": "<WEAPP_DEVTOOLS_PORT>"
            }
        }
    }
}
```
Replace <…> with your own values. 10 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e WEAPP_WS_ENDPOINT=<WEAPP_WS_ENDPOINT> -e WEAPP_AUTOMATOR_MODE=<WEAPP_AUTOMATOR_MODE> -e WEAPP_PROJECT_PATH=<WEAPP_PROJECT_PATH> -e WECHAT_DEVTOOLS_CLI_PATH=<WECHAT_DEVTOOLS_CLI_PATH> -e WEAPP_DEVTOOLS_PORT=<WEAPP_DEVTOOLS_PORT> weapp-agent-mcp npx -y @chaixueyuan/weapp-agent-mcp
```
Replace <…> with your own values. 10 more environment variables are in the server README

## When to use it
- inspect whether Mini Program elements are visible
- capture the current page and its UI state
- run a short regression flow after a UI change
- create a Markdown report from a scenario
- recover a dropped DevTools connection

## Example prompts
- Check the sign-in screen with `mp_screenshot`, then verify the main button with `page_expectVisible`.
- Capture `page_snapshot` for the current route and assert the expected navigation.
- Run a short flow with `mp_runScenario` and create its Markdown report with `mp_generateScenarioReport`.

## Similar
- [mobile-mcp](https://affpapa.org/en/nevibecode/mcp/mobile-mcp.md) — MCP server · ★ 9946
- [mobilerun](https://affpapa.org/en/nevibecode/mcp/mobilerun.md) — MCP server · ★ 9751
- [e2e](https://affpapa.org/en/nevibecode/mcp/e2e.md) — MCP server · ★ 11912
- [XcodeBuildMCP](https://affpapa.org/en/nevibecode/mcp/xcodebuildmcp.md) — MCP server · ★ 6505
- [ShipSwift](https://affpapa.org/en/nevibecode/mcp/shipswift.md) — MCP server · ★ 3244
- [agent-device](https://affpapa.org/en/nevibecode/mcp/agent-device.md) — MCP server · ★ 5149

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md