@weadmin/weixin-minigame-helper-mcp

WeChat Mini Game MCP Server — Preview, debug, real-device test 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 test, 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 a WeChat Mini Game preview. Launches a local dev server and serves the game in a browser.

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

Returns: Local preview URL and port number.

reload_game

Hot-reload the running game preview. If the game is not running yet, it starts automatically.

| Parameter | Type | Required | Description | |---|---|---|---| | workspacePath | string | Only if game not running | Absolute path to the Mini Game directory |

Returns: Confirmation with the preview URL.

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.

real_device_preview

Build and upload the game to WeChat servers for real device testing. 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 compiled (ES modules → WeChat-compatible JS) and served in browser
3. File changes are watched via chokidar for hot-reload
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