wechat-devtools-mcp

Name: wechat-devtools-mcp
Author: WaterTian

ローカル

github.com/WaterTian開発ツール1562 日前に更新

リポジトリ

wechat-devtools-mcp について

wechat-devtools-mcpは、AIエディターをWeChat DevToolsに接続し、ミニプログラムの開発とテストを支援します。7つの集約ツールに加え、タスク手順を示すSkillが用意されています。

主な機能

01IDEのライフサイクルと環境の確認
02ビルド、プレビュー、アップロード
03自動操作と実行時情報の取得
04CDPログ収集とページ遷移
05ページ全体の連結スクリーンショット
06ミニプログラムのプロジェクトファイル参照

活用シーン

01ミニプログラムをビルドしてプレビュー
02UI操作を自動化して実行状態を確認
03ページログを収集し長い画面を撮影

MCP 対応

MCPクライアントに7つの集約ツールを提供し、WeChat DevToolsの操作を可能にします。READMEでは、付属のwechat-devtools Skillとの併用を推奨しています。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "watertian-wechat-devtools": {
      "command": "uvx",
      "args": [
        "wechat-devtools-mcp"
      ],
      "env": {
        "WECHAT_DEVTOOLS_CLI": "<WECHAT_DEVTOOLS_CLI>",
        "WECHAT_PROJECT_PATH": "<WECHAT_PROJECT_PATH>",
        "WECHAT_CLI_TIMEOUT": "<WECHAT_CLI_TIMEOUT>",
        "NODE_PATH": "<NODE_PATH>",
        "WECHAT_CDP_PORT": "<WECHAT_CDP_PORT>",
        "WECHAT_AUTOMATOR_READY_TIMEOUT": "<WECHAT_AUTOMATOR_READY_TIMEOUT>"
      }
    }
  }
}

起動コマンドuvx wechat-devtools-mcp

設定が必要な環境変数

WECHAT_DEVTOOLS_CLI微信开发者工具 CLI 路径。Windows: C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat；macOS: /Applications/wechatwebdevtools.app/Contents/MacOS/cli

WECHAT_PROJECT_PATH默认小程序项目绝对路径，例如 D:\Projects\MyMiniApp

WECHAT_CLI_TIMEOUTCLI 命令超时时间（秒）

NODE_PATHNode.js 可执行文件路径

WECHAT_CDP_PORTCDP 调试端口默认值；9222 被 Chrome 占用时设为 9333

WECHAT_AUTOMATOR_READY_TIMEOUTautomator start 等待首次应答的秒数

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

pypiwechat-devtools-mcp0.9.20stdio

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

微信开发者工具 MCP Server (v0.9.20)

把微信开发者工具封装为 MCP 服务，让编辑器里的 AI 直接完成小程序的编译、预览、调试、自动化测试闭环。Windows / macOS，已上架官方 MCP Registry。

重要

「瘦 MCP + 胖 Skill」：MCP Server 只提供 7 个聚合工具，操作流程与最佳实践都在配套的 wechat-devtools Skill 里。两者必须一起装。

🤝 与官方能力的关系

微信开发者工具 2.x 自 2026-08-18 起为官方 Stable（1.06 已下架），IDE 内建 MCP Server（47 个原子工具，其中 2 个已废弃）。两者互补，不是替代：

场景	用谁
打开项目 / 编译 / 预览 / 上传 / 点击输入 / 云开发	2.x 优先官方内建 MCP（`wechat_ide(action='status')` 的 `official_mcp.available` 为 `true` 即可用）
长图拼接截图（固定头尾识别，拍不全如实上报）	本项目。官方只截视口并压到长边 1280 JPEG
CDP 结构化日志（回放采集前的历史、按页面归类、去噪）	本项目。官方只读缓存
任务级 SOP（一句话跑完巡检 / 异常排查 / 跨页面校验）	本项目 Skill
存量 1.06.x（NW.js）	本项目继续兼容；官方内建 MCP 仅 2.x 有

⚠ 官方 IDE 把自家 bridge 注册为 wechat-devtools。本文示例统一用 wechat-devtools-mcp 避免撞名；旧名配置仍可用，只在同一 agent 同时接入两者时才需区分。

🚀 快速开始

前置条件：Python ≥ 3.10（uv 会自动准备）、Node.js ≥ 18（daemon 依赖 puppeteer-core / jimp）、微信开发者工具 2.x 或 1.06.x。

Step 1 — 安装 MCP Server

pip install uv                                           # 或 brew install uv；已装可跳过
uv tool install wechat-devtools-mcp                      # 首次安装
uv tool install wechat-devtools-mcp --force --refresh    # 升级：--refresh 刷新索引缓存，否则可能装回旧版
wechat-devtools-mcp --version                            # 确认实际运行版本

警告

曾用 pip install 装过旧版的，先 pip uninstall wechat-devtools-mcp，否则旧路径优先于 uv。 ≤0.9.10 与 mcp SDK ≥2.0 不兼容（报 ModuleNotFoundError: mcp.server.fastmcp），请升到 ≥0.9.11。

升级前先停掉编辑器里正在跑的 MCP 进程（重启编辑器即可）。用 uvx 配置的客户端会复用已缓存的环境、不会自动升级：跑一次 uvx --refresh wechat-devtools-mcp --version 刷新，或在 args 里锁定版本 wechat-devtools-mcp==X.Y.Z。

Step 2 — 开启开发者工具服务端口

开发者工具 → 设置 → 安全设置 → 服务端口 → 开启。不开则 open / compile / preview 等走 CLI 的操作全部报 CLI_TIMEOUT。

Step 3 — 准备两个绝对路径

路径	Windows	macOS
开发者工具 CLI	`C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat`	`/Applications/wechatwebdevtools.app/Contents/MacOS/cli`
小程序项目根目录	`D:\MyProjects\mini-app`	`/Users/<you>/Projects/mini-app`

JSON 里 Windows 路径的 \ 要写成 \\；macOS 的 / 不用转义。

Step 4 — 编辑器配置

标准配置（Claude Desktop / Antigravity / Kiro / Trae / Claude Code .mcp.json 通用）：

{
  "mcpServers": {
    "wechat-devtools-mcp": {
      "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"
      }
    }
  }
}

9222 常年被 Chrome 等占用的机器，在 env 里再加一行 "WECHAT_CDP_PORT": "9333"。

编辑器	配置位置	差异
Claude Desktop / Antigravity	`claude_desktop_config.json` / `mcp_config.json`	无
Claude Code（项目级）	仓库根目录 `.mcp.json`	`uvx` 走终端 PATH 即可。若编辑器是 GUI 启动（桌面版）报找不到 `uvx` / `node`，`command` 改绝对路径 `/opt/homebrew/bin/uvx`，并在 `env` 加 `"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"` 与 `"NODE_PATH": "/opt/homebrew/bin/node"`
Kiro	`~/.kiro/settings/mcp.json`	可加 `"autoApprove": ["wechat_ide","wechat_build","wechat_automator","wechat_inspector","wechat_screenshot","wechat_navigate","wechat_file"]`
Trae ≥1.3	AI 面板 → 设置 → MCP → 手动配置；或 `%APPDATA%\Trae\User\globalStorage\mcp.json` / `~/Library/Application Support/Trae/User/globalStorage/mcp.json`	聊天须选 Builder with MCP 智能体；macOS 报找不到 `uvx` 时同上改绝对路径
Cursor / VS Code	MCP 面板新增 server	Name `wechat-devtools-mcp`，Command `uvx wechat-devtools-mcp`，环境变量同上
OpenAI Codex	`~/.codex/config.toml`	TOML，见下

[mcp_servers.wechat-devtools-mcp]
command = "uvx"
args = ["wechat-devtools-mcp"]

[mcp_servers.wechat-devtools-mcp.env]
WECHAT_DEVTOOLS_CLI = "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat"
WECHAT_PROJECT_PATH = "D:\\Your\\Project\\Path"

Step 5 — 安装 Skill（必须）

npx -y skills add WaterTian/wechat-devtools-mcp/.agents/skills/wechat-devtools

不走 npx skills 的客户端（如 Trae）：把仓库的 .agents/skills/wechat-devtools/ 整个复制到小程序项目的 .agents/skills/ 下即可。Skill 含 9 条 SOP、7 工具全 action 速查、CDP 渐进排查策略与故障手册，详见 SKILL.md。

Step 6 — セルフチェック

エディターで wechat_ide(action='status') を一度実行し、以下の項目がすべて条件を満たしていることを確認してから作業を開始してください。

フィールド	期待値	条件を満たさない場合
`cli_exists` / `project_exists` / `node_available`	`true`	Step 3 の2つのパスを確認してください。Node.js ≥ 18 をインストールしてください
`service_port_enabled`	`true`	Step 2 を参照してください
`cdp_port_occupant.kind`	`none` または `ide`	`foreign` はポートを別のブラウザーが使用中であることを示します。`WECHAT_CDP_PORT=9333` を設定してください
`skill_version`	`mcp_version` と一致	Step 5 を再実行して skill のコピーを更新してください

🛠️ ツールボックス

ツール	用途	action / 主なパラメーター
`wechat_ide`	IDE のライフサイクル管理と環境診断	`open` `login` `is_login` `close` `quit` `status`
`wechat_build`	ビルドと公開	`compile` `preview` `upload` `build_npm` `cache_clean`
`wechat_automator`	自動操作とランタイム情報の照会	`start` `tap` `input` `element_info` `set_data` `call_method` `call_wx` `mock_wx` `evaluate` `page_stack` `page_data` `system_info` `storage`
`wechat_inspector`	ランタイムログの収集	`console` `cdp`
`wechat_screenshot`	縦長スクリーンショットの結合	`full_page` `page_path` `scroll_top`
`wechat_navigate`	ページ遷移と CDP ログの収集	`page_path`
`wechat_file`	プロジェクトファイルの読み込み	`project_info` `list_pages` `read_page` `read_file`

アクションで automator への接続に失敗した場合は、自動的に一度 start を実行して再試行します（auto_recovered が返されます）。open が成功すると、同じセッション内では cdp_port が自動的に引き継がれるため、ほかのツールに渡す必要はありません。すべてのパラメーターについては MCP_DOC.md を参照してください。クラウド関数とクラウドデータベースには CloudBase MCP を使用してください。

💡 環境変数

変数	説明	デフォルト
`WECHAT_DEVTOOLS_CLI`	開発者ツール CLI のパス（必須）	—
`WECHAT_PROJECT_PATH`	デフォルトのプロジェクトルートディレクトリ（必須）	—
`WECHAT_CLI_TIMEOUT`	CLI のタイムアウト秒数	`30`
`WECHAT_CDP_PORT`	CDP デバッグポートのデフォルト値。9222 が Chrome によく使用されている場合は `9333` に設定します。`open` が成功すると、同じセッション内のほかのツールにも自動的に引き継がれます	`9222`
`WECHAT_AUTOMATOR_READY_TIMEOUT`	`start` が automator からの最初の応答を待つ秒数です。大規模プロジェクトのコールドスタート時は値を大きくできます	`45`
`NODE_PATH`	Node.js 実行ファイル	`node`

❓ よくある問題

症状	対処方法
`CLI_TIMEOUT` が繰り返し報告される	サービスポートが開いていません。Step 2 を参照してください。`wechat_ide(action='status')` の `service_port_enabled` で確認できます
CDP の収集に失敗する／収集結果がすべて別のページになる	`status` の `cdp_port_occupant.kind` が `foreign` の場合、ポートを別のブラウザーが使用中です。`open(cdp_port=9333)` を指定するか、`WECHAT_CDP_PORT` を設定してください。その後は、ほかのツールにポートを渡さなくても自動的に引き継がれます。0.9.19 以降、`open` は直接エラーを報告し、他者のページのエラーを起動エラーとして扱わなくなりました
automator の 9420 に接続できない／`start` が `verified=false` を返す	0.9.19 以降、アクションで接続が切れた場合は自動的に一度 `start` を実行して再試行します。`start` は最大45秒間、準備完了を待機します（`ready_timeout` で調整可能です）。それでも失敗する場合は、`status` の `project_window_open` を確認してください。ウィンドウが閉じている場合は `start` を再実行し、先に `open` で IDE を再起動しないでください
Windows で中国語が文字化けする、または `UnicodeDecodeError` が発生する	`env` に `"PYTHONIOENCODING": "utf-8"` を追加してください
新しいバージョンをインストールしたのに古いバージョンが実行される	`pip uninstall wechat-devtools-mcp` を実行してください。`uvx` 方式で実行している場合は `uvx --refresh wechat-devtools-mcp --version` を実行してください。最後に `status` の `mcp_version` を確認してください
IDE 2.x でツールの動作に異常がある	登録名が公式の `wechat-devtools` と重複しているため、`wechat-devtools-mcp` を使用してください

📋 バージョン履歴

バージョン	日付	概要
0.9.20	2026-10-26	`call_wx` の同期 wx API は自動的に evaluate 経由で直接呼び出されるようになり、10秒でタイムアウトしなくなりました。README / MCP_DOC / SKILL をフィールドごとに照合して修正しました。Node.js ≥ 18 の要件を明記しました
0.9.19	2026-10-26	automator の `start` が期限まで準備完了を待機するようになり、「ハンドシェイク未完了」の誤報を根本的に解消しました。CDP ポートの使用状況検出とセッション内でのポート引き継ぎ（`WECHAT_CDP_PORT`）に対応しました。automator の接続切断から自動復旧するようになりました。`status` にプロジェクトウィンドウ／skill バージョンの診断を追加しました
0.9.18	2026-09-04	Windows 2.x で実機を使った一連の動作確認に対応しました。状態ディレクトリの `User Data` レイヤー、準備完了の判定条件、終了を待つ `quit`、ノイズフィルターを追加しました。実機スモークテストスクリプトを追加しました
0.9.17	2026-09-03	開発者ツール 2.x Stable に対応しました。evaluate に `fn_source` を追加しました。`open` の速度が約4倍になりました。Windows 1.x／2.x の両方を判定できるようになりました
0.9.16	2026-08-27	長いページのスクリーンショットを全面的に修正しました。ソースコードをオープンソース化しました
0.9.15	2026-08-20	開発者ツール 2.x（Electron）に対応しました。0.9.0 以降 CDP の収集結果が常に0件になる問題を修正しました
0.9.14	2026-08-20	`wechat_file` のパスの扱いを統一しました。`cdp_port` の引き渡しを修正しました
0.9.13	2026-08-18	`--version` を早期終了するようにしました。ドキュメントを照合して修正しました

各バージョンの詳細については CHANGELOG.md を参照してください。

参考

微信開発者ツール CLI · ミニプログラム自動化 SDK
ライセンス：MIT

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。