@weadmin/weixin-minigame-helper-mcp

WeChat Mini Game MCP Server — Preview, debug, real-device preview and publish WeChat Mini Games from any MCP-compatible AI coding assistant.

Overview

This package provides a Model Context Protocol (MCP) server that enables AI coding assistants (such as Claude, CodeBuddy, Cursor, etc.) to preview, hot-reload, real-device preview, and publish WeChat Mini Games — all through natural language.

Quick Start

Use with npx (recommended)

No installation needed. Configure your MCP client with:

{
  "mcpServers": {
    "weixin-minigame-helper": {
      "command": "npx",
      "args": [
        "-y",
        "--prefer-online",
        "@weadmin/weixin-minigame-helper-mcp@latest"
      ]
    }
  }
}

Global install

npm install -g @weadmin/weixin-minigame-helper-mcp

Then configure your MCP client with:

{
  "mcpServers": {
    "weixin-minigame-helper": {
      "command": "weixin-minigame-helper-mcp"
    }
  }
}

MCP Tools

This server exposes the following tools:

run_game

Start or hot-reload a WeChat Mini Game preview. Idempotent — call this every time the game code is created or modified. The first call launches a local dev server and serves the game in a browser; subsequent calls re-bundle the code and refresh the open preview page automatically. The preview URL and port stay the same across calls.

| Parameter | Type | Required | Description | |---|---|---|---| | workspacePath | string | ✅ | Absolute path to the Mini Game directory (must contain game.js) |

Returns: Local preview URL and port number (stable across calls).

get_logs

Retrieve console log entries (log / warn / error) from the running game.

| Parameter | Type | Required | Description | |---|---|---|---| | filter | string | ❌ | JavaScript regex pattern to filter log messages (case-insensitive) |

Returns: Formatted log entries with timestamps and log levels.

capture_screenshot

Capture a screenshot of the currently running game canvas. Supports all game types: Canvas2D, WebGL (Unity, Cocos, Three.js, etc.).

| Parameter | Type | Required | Description | |---|---|---|---| | format | string | ❌ | Image format: "image/png" (default) or "image/jpeg" | | quality | number | ❌ | JPEG quality 0-1 (default: 0.92). Ignored for PNG |

Requires: Game must be running (call run_game first).

Returns: Base64-encoded screenshot image of the game canvas.

real_device_preview

Build and upload the game to WeChat servers for real device preview. Generates a QR code that can be scanned with WeChat.

| Parameter | Type | Required | Description | |---|---|---|---| | workspacePath | string | ✅ | Absolute path to the Mini Game directory |

Requires: AppID and upload private key (see Configuration).

Returns: QR code displayed in the browser preview page.

publish

Upload the game to the WeChat platform as a development version.

| Parameter | Type | Required | Description | |---|---|---|---| | workspacePath | string | ✅ | Absolute path to the Mini Game directory | | version | string | ✅ | Version number (semver, e.g. "1.0.0") | | desc | string | ❌ | Optional release notes |

Returns: Upload confirmation with version and AppID info.

Note: This uploads as a development version. To promote to experience/production, use the WeChat MP Admin Console.

Configuration

For real-device preview and publish, you need to provide:

1. AppID — Your WeChat Mini Game AppID
2. Upload Private Key — The private key file for CI uploads (download from WeChat MP Admin Console → Development → Development Settings → Mini Program Code Upload Key)

Option 1: Browser UI

1. Start a preview with run_game
2. Click the ⚙️ settings button in the browser preview page
3. Fill in your AppID and upload the private key file

Option 2: Environment Variables

export WECHAT_APPID="your_appid_here"
export WECHAT_PRIVATE_KEY_PATH="/path/to/private.key"
# Or provide the key content directly:
export WECHAT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."

IP Whitelist

WeChat requires your server's public IP to be whitelisted for CI uploads. Add your IP in WeChat MP Admin Console → Development → Development Settings → IP Whitelist.

Tip: The preview page displays your current public IP in the top-right corner for easy copying.

How It Works

AI Assistant ←→ MCP Protocol (stdio) ←→ This Server ←→ Local Dev Server + miniprogram-ci
                                                              ↓
                                                        Browser Preview
                                                        Real Device QR
                                                        WeChat Upload

1. The MCP server starts a local Express dev server for game preview
2. Game source files are pre-bundled into a single browser-compatible IIFE and served via the local dev server
3. File changes trigger a re-bundle; the open preview page reloads automatically without changing port or URL
4. Real-device preview and publish use miniprogram-ci for WeChat platform integration

Requirements

• Node.js >= 16
• A WeChat Mini Game project with game.js entry file
• For real-device / publish: WeChat AppID + upload private key

License

MIT