pip install uv   # Install uv if not present
uv tool install wechat-devtools-mcp --force  # Install wechat-devtools-mcp via uv

{
  "mcpServers": {
    "wechat-devtools": {
      "command": "uvx",
      "args": ["wechat-devtools-mcp"],
      "env": {
        "WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat",
        "WECHAT_PROJECT_PATH": "D:\\Your\\Project\\Path"
      }
    }
  }
}

See README.md for mainstream editor configurations

[!IMPORTANT] You must manually enable the service port of the developer tools:

Settings

→

Security Settings

→

Service Port

→

Enable

. Failure to enable will cause all CLI operations to report

CLI_TIMEOUT

.

First call

wechat_ide(action='status')

to verify all prerequisites at once.

status

cli_exists: true

WECHAT_DEVTOOLS_CLI

status

project_exists: true

WECHAT_PROJECT_PATH

is_login

logged_in: true

login(qr_format='terminal')

status

node_available: true

The IDE is opened only once at the start of the session, compile is executed only after code changes, and page navigation uses evaluate preferentially over navigate.

evaluate(expression="wx.reLaunch({url:'/pages/xxx/index'}); 'ok'")

page_data

compile

page_data

start

compile

• Note: compile_condition may be invalid for tabBar pages (overridden by app route guards), using evaluate + wx.reLaunch for navigation is more reliable

preview

qr_format="terminal"

upload

version

desc?

build_npm

cache_clean

clean_type="compile"

Prerequisite: Call

start

first to enable the automation port (only required once per session).

start

tap

selector

input

selector

value

element_info

selector

set_data

data_json

call_method

method

args_json?

call_wx

method

mock_wx

method

result_json

evaluate

expression

• Note: Declaration statements (const/let/var) are supported since v0.7.0
• v0.9.2: Automatically invalidates old cache connections and reconnects after compile, adds 3s timeout protection for daemon health check, and 2s independent timeout for navigate currentPage polling
• v0.9.0:底层改为持久化 Node daemon（NDJSON 协议），WS 连接按端口缓存复用，工具调用延迟 ~3ms

page_stack

page_data

expected_path?

system_info

storage

key?

console

duration=10

log_type="all"

cdp

duration=10

detail_level="concise"

max_logs=50

CDP Prerequisite: Open the project with

cdp_enabled=true

and ensure port 9222 is available.

• output_path

  (optional): Screenshot save path. Leave blank to automatically save to the

  screenshots/

  folder under the project directory

• full_page

  (default

  true

  ): Set to

  false

  to capture only the current viewport

• scroll_top

  (optional): Position to scroll to before taking the screenshot (logical pixels), use with

  full_page=false

• page_path

  (optional): Ensure being on the specified page before taking the screenshot, automatically navigate if current page does not match
• Prerequisite: Call

  wechat_automator(action='start')

  first
• Note: Do not take screenshots actively, only call when explicitly requested by the user or visual confirmation is needed for troubleshooting
• Limitation: Pages using

  scroll-view

  component cannot be stitched into long screenshots (automator SDK limitation), only the current viewport is captured
• Limitation: Screenshots may not capture fixed/absolute overlays (pop-ups, masks), rely on

  page_data

  instead
• Path Convention: Recommended to use

  <project>/screenshots/

  or explicit absolute path. Avoid writing to

  .claude/image-cache/

  — this is the user image cache directory for Claude Code, mixing MCP screenshots will cause mutual contamination

• page_path

  (required): e.g.

  pages/index/index

• wait_ms

  : Wait time in milliseconds, recommended 3000

• clear_logs

  : Whether to filter historical CDP logs, default

  true

• check_data

  : Whether to check for empty page_data after navigation, default

  true

• detail_level

  :

  concise

  (only errors+warnings) or

  full

• Added in v0.8.0: Automatically detects TabBar pages and uses

  switchTab

  instead of

  reLaunch

  , returns

  navigation_method

  field
• Prerequisite: Requires

  automator start

  +

  cdp_enabled=true

project_info

list_pages

read_page

page_path

read_file

file_path

Cloud Function and Cloud Database Management: This MCP no longer provides

wechat_cloud

tools since v0.9.5. Please use CloudBase MCP instead (with

manageFunctions

/

readNoSqlDatabaseContent

/

writeNoSqlDatabaseContent

etc.), which has no IDE dependency and covers more features.

wechat_ide(action='status')                         # Diagnose environment
wechat_ide(action='is_login')                       # Check login status
  ↳ Not logged in: wechat_ide(action='login', qr_format='terminal')
wechat_ide(action='open', cdp_enabled=True)         # Launch IDE + CDP 9222 + automatic health check
  ↳ Returns success=false + startup_errors → Fatal error during mini program startup, must fix before proceeding
  ↳ Returns success=true → Startup normal, proceed to next steps
  ↳ Transient errors may occur during IDE cold start (simulator not found / subPackages of undefined), which is normal, ignore and continue to execute compile to refresh
wechat_automator(action='start')                    # Launch daemon + enable automation port 9420
wechat_file(action='project_info')                  # [Optional] Confirm project structure
wechat_build(action='cache_clean', clean_type='all')     # Clear all cache
wechat_build(action='compile')                            # Compile to establish clean CDP baseline (automatically reconnects automator)
wechat_automator(action='page_data')                # Verify connection availability
  ↳ ⚠ Check if AppID is undefined in the output
  ↳ If undefined → project_path may point to a subdirectory instead of the project root
  ↳ Cloud development project root directory contains project.config.json, miniprogram/ and cloudfunctions/
  ↳ Correct: project_path="D:/MyProject"  Wrong: project_path="D:/MyProject/miniprogram"

project_path Rule: Must point to the root directory containing

project.config.json

. For cloud development projects,

miniprogram/

is a subdirectory and cannot be used as project_path.

wechat_build(action='compile')                      # Compile (automatically reconnects automator)
wechat_automator(action='page_data')                # Verify connection availability

No need to re-open IDE or perform cache_clean. Only execute after modifying mini program source code.

wechat_automator(action='mock_wx', method='requestPayment', result_json='{"errMsg":"requestPayment:ok"}')
wechat_automator(action='mock_wx', method='getUserProfile',  result_json='{"userInfo":{"nickName":"Test User"}}')
wechat_automator(action='mock_wx', method='getLocation',     result_json='{"latitude":23.099,"longitude":113.324}')
wechat_automator(action='tap', selector='.pay-btn')         # Trigger interaction
wechat_automator(action='page_data')                        # Verify data changes

Mock is only valid for the current session, needs to be reset after restarting IDE.

concise → Only errors + warnings (saves tokens, preferred)
  ↓ When summary.errors > 0
full    → Complete logs + source location → wechat_file(action='read_file', file_path=source)

duration=5, detail_level='concise', max_logs=20

duration=10, detail_level='full', max_logs=100

duration=3, detail_level='concise', max_logs=30

Important: CDP error count may include accumulated historical logs across pages.

clear_logs=true

(default) in v0.4.0 filters historical logs based on timestamp, but it is still recommended to use

page_data

as the final verification standard.

devtools://devtools/

ide:///extensions/

console.assert

SharedArrayBufferIssue

getSystemInfo API prompt

wx.saveFile will be deprecated

wx.removeSavedFile will be deprecated

[Component] property "xxx" received type-uncompatible value

Judgment Principle: The errors/warnings count in CDP may be inflated by the above noise, leading to misjudgment. Always use the actual data returned by

page_data

as the final verification standard.

1. Must verify the path field: The returned

   data.path

   represents the current actual page. If it does not match the navigation target, it means the page navigation failed or was redirected.
2. Common reasons for inconsistency:
   • User not logged in, page intercepts and redirects to login/welcome page
   • Cloud function call failed (AppID undefined), page falls back to homepage
   • page_path spelling error, navigate fails silently (returns success: true)
   • Conditional navigation logic exists in page onLoad
3. Recommended Pattern:

   wechat_navigate(page_path='pages/xxx/index', wait_ms=3000)
   wechat_automator(action='page_data')
     ↳ data.path !== 'pages/xxx/index' → Page not loaded correctly
     ↳ Use page_stack to view complete page stack, locate redirection reason

• ❌ Continue executing subsequent test operations after

  open

  returns

  startup_errors

  (must fix errors first)
• ❌ Call

  preview

  /

  upload

  without confirming

  is_login: true

• ❌ Call

  cache_clean(clean_type='all')

  on production projects
• ❌ Execute

  eval()

  or unsafe code in

  evaluate

• ❌ Assume running status — must rely on actual data returned by MCP interfaces
• ❌ Retry the same failed operation more than 3 times (should switch to diagnosing root cause)
• ❌ Use

  sleep

  hard wait in automated testing (use

  wait_ms

  or poll

  page_data

  )
• ❌ Actively call screenshot in SOP process — only take screenshots when explicitly requested by user or visual confirmation is needed for troubleshooting
• ❌ Directly perform full recovery when connection is disconnected (should first perform quick recovery: only

  start

  →

  page_data

  )
• ❌ Compile without code changes (wastes time, directly navigate with evaluate)
• ❌ Do not verify automator connection after compile (v0.8.0 automatically reconnects, but need

  page_data

  confirmation)
• ❌ Use

  miniprogram/

  subdirectory as project_path for cloud development projects
• ❌ Do not verify if

  page_data.path

  matches expected page after navigate
• ❌ Treat

  console.assert

  from

  devtools://

  source in CDP logs as application errors
• ❌ Use

  wechat_automator

  in multiple parallel Agents (port 9420 is exclusive)
• ✅

  output_path

  of

  wechat_screenshot

  is optional, leave blank to automatically save to project

  screenshots/

  directory
• ✅ Must call

  automator(action='start')

  before using any automation/screenshot features
• ✅ Use

  element_info

  to confirm element exists before executing

  tap

  /

  input

• ✅ Confirm version number has been incremented and

  build_npm

  has been executed before

  upload

• ✅ Pay attention to

  [Violation]

  marks in CDP logs (render blocking/performance issues)
• ✅ Check if AppID is undefined after

  compile

• ❌ Use Chinese quotes

  ""

  or unescaped double quotes in WXML attribute values (compilation error that cannot be detected by tools)
• ✅ Execute

  open

  →

  start

  →

  compile

  to restore connection after screenshot/operation failure
• ✅ Must verify current page path via

  page_data

  or

  page_stack

  after navigate
• ✅ Compare consistency of fields with the same name in cross-page testing