WeChat Mini Program MCP Server

Model Context Protocol (MCP) server for WeChat Mini Program automation using the official miniprogram-automator SDK.

---

Features

• LLM-Friendly: 65 AI-optimized tools for natural language automation
• Complete Coverage: Automator, MiniProgram, Page, Element, Assert, Snapshot, Record, Network tools
• Robust Runtime: Built-in timeout protection and retry mechanism for all async operations
• Zero Config: Auto-detects project path from project.config.json or app.json
• npx Ready: No installation needed, just npx -y @creatoria/miniapp-mcp
• Test Automation: Built-in assertion and recording capabilities
• TypeScript: Full type definitions with comprehensive test coverage

Quick Start

Installation

Use with npx (recommended):

npx -y @creatoria/miniapp-mcp

Or install globally:

npm install -g @creatoria/miniapp-mcp

Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "miniprogram": {
      "command": "npx",
      "args": ["-y", "@creatoria/miniapp-mcp"]
    }
  }
}

That’s it! The server will automatically detect your mini program project.

How It Works

The server wraps WeChat’s official miniprogram-automator SDK, exposing it through the Model Context Protocol. This allows AI assistants like Claude to:

1. Connect to WeChat DevTools automation interface
2. Control mini program UI through natural language
3. Verify behavior with built-in assertions
4. Debug with snapshots and recordings

Auto-Detection

The server automatically searches for mini program projects:

• Current directory (checks for project.config.json or app.json)
• Common subdirectories: dist/, build/, miniprogram/, src/

Available Tools

Core Tools (65 total)

Runtime Features

Timeout Protection

All async operations are protected with configurable timeouts to prevent hanging:

Configuring Timeouts

All timeouts are configurable via .mcp.json (values in milliseconds):

{
  "projectPath": "/path/to/miniprogram",
  "timeout": 30000,
  "evaluateTimeout": 5000,
  "launchTimeout": 60000,
  "connectTimeout": 30000,
  "screenshotTimeout": 10000
}

See Toolchain Version Baseline & Timeout Configuration for tuning guidance.

Retry Mechanism

Transient errors are automatically retried with configurable strategies:

• Default: 2 retries with 1s delay
• Exponential backoff available
• Custom retry predicates supported

Requirements

• Node.js: >= 18.0.0
• WeChat DevTools: Download
  • Recommended: latest stable (v2.01.2510260 / 2025-10 or newer)
  • Minimum for auto command: v1.05.2111232
  • Enable CLI/HTTP calls in Settings -> Security
  • Default automation port: 9420
• miniprogram-automator: 0.12.1 (2023-11-07) — the official SDK is no longer actively maintained but remains functional
• Mini Program Project: Any WeChat mini program with project.config.json or app.json

See Toolchain Version Baseline for full version and compatibility details.

Examples

Natural Language Testing

You: "Launch the mini program and navigate to the product list page"

Claude: [Calls miniprogram_connect + miniprogram_navigate]
Connected to DevTools
Navigated to pages/product/list

You: "Find the first product title and verify it contains 'iPhone'"

Claude: [Calls page_query + element_get_text + assert_text_contains]
Found element with text: "iPhone 15 Pro"
Assertion passed: text contains "iPhone"

Screenshot with Base64 Return

You: "Take a screenshot and show me what the page looks like"

Claude: [Calls miniprogram_screenshot with returnBase64=true]
Screenshot captured successfully (base64 returned directly)

Programmatic Usage

See examples/ directory for complete workflows:

• Basic Navigation
• Element Interaction
• Assertion Testing
• Snapshot Debugging
• Action Recording

Documentation

• Directory & Code Guidelines
• Migration Overview
• Runtime Skeleton Mapping
• Tool Schema Strategy
• Troubleshooting - Common issues and solutions

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

# Lint
pnpm lint

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Links

• npm Package
• GitHub Repository
• Model Context Protocol
• WeChat Mini Program Automator
• WeChat DevTools

---

Made with love for the WeChat Mini Program developer community