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.

Custom Project Path

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

Using Config File

Create .mcp.json in your project root:

{
  "projectPath": "/path/to/miniprogram",
  "cliPath": "/Applications/wechatwebdevtools.app/Contents/MacOS/cli",
  "port": 9420,
  "capabilities": ["core", "assert", "snapshot", "record", "network"]
}

Then use:

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

Environment Variables

export MCP_PROJECT_PATH=/path/to/miniprogram
export MCP_PORT=9420
export MCP_CAPABILITIES=core,assert,snapshot

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)

| Tool | Description | |------|-------------| | miniprogram_launch | Launch WeChat Mini Program with automator | | miniprogram_connect | Connect to running DevTools instance | | miniprogram_disconnect | Disconnect but keep IDE running | | miniprogram_close | Close session and cleanup resources |

| Tool | Description | |------|-------------| | miniprogram_navigate | Navigate using navigateTo/redirectTo/reLaunch/switchTab/navigateBack | | miniprogram_call_wx | Call WeChat API methods (wx.*) | | miniprogram_evaluate | Execute JavaScript in mini program context | | miniprogram_screenshot | Take screenshots (supports base64 return and fullPage mode) | | miniprogram_get_page_stack | Get current page stack | | miniprogram_get_system_info | Get system information |

| Tool | Description | |------|-------------| | page_query | Query single element | | page_query_all | Query all matching elements | | page_wait_for | Wait for condition or selector | | page_get_data | Get page data | | page_set_data | Set page data | | page_call_method | Call page methods | | page_get_size | Get page dimensions | | page_get_scroll_top | Get scroll position |

| Tool | Description | |------|-------------| | element_tap | Tap/click element | | element_longpress | Long press element | | element_input | Input text (input/textarea) | | element_get_text | Get text content | | element_get_attribute | Get element attribute | | element_get_property | Get element property | | element_get_value | Get element value | | element_get_size | Get element size | | element_get_offset | Get element offset | | element_trigger | Trigger custom events | | element_get_style | Get element style | | element_touchstart | Touch start event | | element_touchmove | Touch move event | | element_touchend | Touch end event | | element_scroll_to | Scroll to position (ScrollView) | | element_scroll_width | Get scroll width (ScrollView) | | element_scroll_height | Get scroll height (ScrollView) | | element_swipe_to | Swipe to index (Swiper) | | element_move_to | Move to position (MovableView) | | element_slide_to | Slide to value (Slider) | | element_call_context_method | Call context method | | element_set_data | Set data on custom element | | element_call_method | Call method on custom element |

| Tool | Description | |------|-------------| | assert_exists | Assert element exists | | assert_not_exists | Assert element doesn't exist | | assert_text | Assert text equals expected | | assert_text_contains | Assert text contains substring | | assert_value | Assert value equals expected | | assert_attribute | Assert attribute equals expected | | assert_property | Assert property equals expected | | assert_data | Assert page data equals expected | | assert_visible | Assert element is visible |

| Tool | Description | |------|-------------| | snapshot_page | Capture page snapshot (data + screenshot) | | snapshot_full | Capture full app snapshot (system + page stack) | | snapshot_element | Capture element snapshot |

| Tool | Description | |------|-------------| | record_start | Start recording actions | | record_stop | Stop and save recording | | record_list | List saved recordings | | record_get | Get recording details | | record_delete | Delete recording | | record_replay | Replay recorded actions |

| Tool | Description | |------|-------------| | network_mock_wx_method | Mock WeChat API methods | | network_restore_wx_method | Restore mocked methods | | network_mock_request | Mock wx.request responses | | network_mock_request_failure | Mock request failures | | network_restore_request | Restore wx.request | | network_restore_all_mocks | Restore all mocks |

Runtime Features

Timeout Protection

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

| Operation | Default Timeout | |-----------|----------------| | Navigation | 30s | | Screenshot (viewport) | 10s | | Screenshot (fullPage) | 30s | | wx.* API calls | 10s | | Page stack queries | 5s | | System info queries | 5s | | Element queries | 10s | | Wait operations | 30s |

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
  • Enable CLI/HTTP calls in Settings -> Security
  • Default automation port: 9420
• Mini Program Project: Any WeChat mini program with project.config.json or app.json

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