微信（WeChat）ミニプログラム MCP サーバー

FastMCPベースのサーバーであり、miniprogram-automator を通じて微信開発者ツールを自動化します。このサーバーはMCPツールを提供し、AIアシスタントがミニプログラムのページをナビゲート、検査、操作できるようにします。playwright-mcp に似ていますが、微信エコシステム向けにカスタマイズされています。

前提条件

• 微信開発者ツールがインストールされており、コマンドラインアクセス（cli / cli.bat）がサポートされていること

• ローカルに Node.js 18+ および npm がインストールされていること

• 開発者ツールで開くことができるミニプログラムプロジェクトがあること

クイックスタート（npm パッケージ）

@yfme/weapp-dev-mcp はnpmに公開されています。一般的なユーザーはリポジトリをクローンしたり、手動で node dist/index.js を実行したりする必要はありません。

npx で実行

npx -y @yfme/weapp-dev-mcp

プロジェクト/グローバルへのインストール

npm install -g @yfme/weapp-dev-mcp
weapp-dev-mcp

またはプロジェクトの依存関係として追加：

npm install --save-dev @yfme/weapp-dev-mcp
npx weapp-dev-mcp

本リポジトリ内で開発する場合にのみ、直接 node dist/index.js を実行することをお勧めします。一般ユーザーは上記のnpmパッケージ方式で起動してください。

MCP クライアント統合

設定

Claude Desktopやその他のMCPクライアントでこのサーバーを使用するには、設定ファイルに以下を追加してください：

{
  "mcpServers": {
    "weapp-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@yfme/weapp-dev-mcp"
      ],
      "env": {
        "WEAPP_WS_ENDPOINT": "ws://localhost:9420"
      }
    }
  }
}

Claude Code のツール権限の自動承認

Claude Codeを使用してMCPツールを呼び出す際、ツール呼び出しの権限申請がトリガーされます。このとき、MCPと微信開発者ツール間の接続状態が失われる可能性があり、コンソール出力の取得は接続状態に大きく依存するため、ログを連続的に取得できなくなることがあります。そのため、手動で権限を追加することをお勧めします。

プロジェクトディレクトリに .claude/settings.local.json ファイルを作成するか、既存のファイルに以下の内容を追加することで、確認なしで直接ツールを呼び出せるようになります。または、必要に応じて確認なしで呼び出しを許可するツールを追加してください：

{
  "permissions": {
    "allow": [
      "mcp__weapp-dev-mcp__mp_ensureConnection",
      "mcp__weapp-dev-mcp__mp_navigate",
      "mcp__weapp-dev-mcp__mp_screenshot",
      "mcp__weapp-dev-mcp__mp_callWx",
      "mcp__weapp-dev-mcp__mp_getLogs",
      "mcp__weapp-dev-mcp__mp_currentPage",
      "mcp__weapp-dev-mcp__mp_listProjects",
      "mcp__weapp-dev-mcp__mp_setDefaultProject",
      "mcp__weapp-dev-mcp__page_getElement",
      "mcp__weapp-dev-mcp__page_getElements",
      "mcp__weapp-dev-mcp__page_waitElement",
      "mcp__weapp-dev-mcp__page_waitTimeout",
      "mcp__weapp-dev-mcp__page_getData",
      "mcp__weapp-dev-mcp__page_setData",
      "mcp__weapp-dev-mcp__page_callMethod",
      "mcp__weapp-dev-mcp__element_tap",
      "mcp__weapp-dev-mcp__element_input",
      "mcp__weapp-dev-mcp__element_callMethod",
      "mcp__weapp-dev-mcp__element_getData",
      "mcp__weapp-dev-mcp__element_setData",
      "mcp__weapp-dev-mcp__element_getInnerElement",
      "mcp__weapp-dev-mcp__element_getInnerElements",
      "mcp__weapp-dev-mcp__element_getWxml",
      "mcp__weapp-dev-mcp__element_getStyles",
      "mcp__weapp-dev-mcp__element_scrollTo",
      "mcp__weapp-dev-mcp__element_getAttributes",
      "mcp__weapp-dev-mcp__element_getBoundingClientRect"
    ]
  }
}

注意： ツール名の形式は mcp__<サーバー名>__<ツール名> です。サーバー名がMCP設定内の名前と一致していることを確認してください。

微信開発者ツールの起動

MCPサーバーを使用する前に、微信開発者ツールを起動し、WebSocketサービスを有効にする必要があります。

💡 開始する前に：

1. 微信開発者ツールを開く

2. 設定 → セキュリティ設定 → サービスポート に移動

3. 「HTTPデバッグ」 と 「自動テスト」 を有効にする

コマンドラインを使用して起動

コマンドラインを使用して微信開発者ツールを起動し、自動的にWebSocketサービスを有効にします：

macOS/Linux：

/Applications/wechatwebdevtools.app/Contents/MacOS/cli auto --project /path/to/your/project --auto-port 9420

Windows：

"C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat" auto --project C:\path\to\your\project --auto-port 9420

ここで：

• --project パラメータはミニプログラムプロジェクトのディレクトリパスを指定します（実際のプロジェクトパスに置き換えてください）

• --auto-port パラメータはWebSocketサービスのポートを指定します（デフォルトは9420）

⚠️ 警告 サンドボックスメカニズムのため、一部のクライアントではMCPがプロジェクトディレクトリ外の微信開発者ツールのcliにアクセスすることを許可していません。そのため、ここではWebSocketサービスを使用する方法のみを紹介しています。

環境変数の設定

環境変数を通じて、自動化ツールがどのように微信開発者ツールに接続するかを制御します：

注意： 開発者ツールを起動する（launch モード）際、MCPツールのパラメータを通じてミニプログラムプロジェクトのディレクトリを提供する必要があります：操作を実行する前に connection.projectPath を通じて提供します（例：mp_ensureConnection を使用）。この値は一度確立されると、後続の呼び出しで保持されます。

ツール呼び出しは、connection オブジェクトを通じてこれらのデフォルト値の大部分を上書きできます。

利用可能なツール

アプリケーションツール（Application Tools）

• mp_ensureConnection – 自動化セッションの準備ができていることを確認します。強制再接続や接続設定の上書きが可能です

• mp_navigate – ミニプログラム内をナビゲートします。navigateTo、redirectTo、reLaunch、switchTab、または navigateBack をサポート

• mp_screenshot – スクリーンショットをキャプチャして返します（またはディスクに保存）

• mp_callWx – 微信ミニプログラムAPIメソッドを呼び出します（例：wx.showToast）

• mp_getLogs – ミニプログラムのコンソールログを取得します。取得後にクリアするオプションがあります

• mp_currentPage – 現在のページ情報（パス、クエリパラメータ、サイズ、スクロール位置）を取得します。withData がtrueの場合、ページデータも追加で返されます

• mp_listProjects – 微信開発者ツール内の最近のプロジェクトをリストアップし、プロジェクトディレクトリの選択を容易にします

• mp_setDefaultProject – デフォルトのミニプログラムプロジェクトパスを設定します。設定後、次回の接続時に自動的にそのプロジェクトが使用されます

ページツール（Page Tools）

• page_getElement – セレクターを通じてページ要素を取得し、要素の概要情報（tagName、text、value、size、offset）を返します。withWxml: true を設定すると、完全なouterWxmlが追加で返されます。[index=N] 構文によるN番目の要素の選択をサポート

• page_getElements – セレクターを通じてページ要素の配列を取得し、各要素の概要情報を返します。withWxml: true を設定すると、各要素の完全なouterWxmlが追加で返されます。[index=N] 構文をサポート

• page_waitElement – 要素がページ上に表示されるのを待ちます（⚠️ カスタムコンポーネント内部の要素には適用されません）。[index=N] 構文をサポート。タイムアウトおよびリトライ間隔パラメータを追加

• page_waitTimeout – 指定されたミリ秒数だけ待機します

• page_getData – 現在のページのデータオブジェクトを取得します。パスを指定可能です（'user.name' のようなネストされたパスをサポート）

• page_setData – setData を使用して現在のページのデータを更新します。データが実際に正常に更新されたかを確認する verify オプションを追加

• page_callMethod – 現在のページインスタンスで公開されているメソッドを呼び出します

要素ツール（Element Tools）

• element_tap – CSSセレクターを通じてWXML要素のクリックをシミュレートします。[index=N] 構文によるN番目の要素の選択をサポート。x/y座標オフセットクリックをサポート。安定性の強化：要素がインタラクティブな状態になるのを待ち、クリック後にページパスが変更されたかを自動検証

• element_input – 要素にテキストを入力します（input および textarea コンポーネントに適用）

• element_callMethod – カスタムコンポーネントインスタンスのメソッドを呼び出します

• element_getData – カスタムコンポーネントインスタンスのレンダリングデータを取得します

• element_setData – カスタムコンポーネントインスタンスのレンダリングデータを設定します

• element_getInnerElement – 要素内の要素を取得します（element.$(selector) に相当）。要素の概要情報を返します。withWxml: true を設定すると、完全なouterWxmlが追加で返されます

• element_getInnerElements – 要素内の要素の配列を取得します（element.$$(selector) に相当）。要素の概要情報を返します。withWxml: true を設定すると、各要素の完全なouterWxmlが追加で返されます

• element_getWxml – 要素のWXML（内部または外部）を取得します

• element_getStyles – 要素のCSSスタイル値を取得します。namesパラメータはスタイル名の配列です（例：['color', 'fontSize']）

• element_scrollTo – scroll-viewコンポーネントを指定位置（x, y）にスクロールします

• element_getAttributes – 要素の属性値を取得します。namesパラメータは属性名の配列です（例：['class', 'id', 'data-index']）

• element_getBoundingClientRect – ビューポートに対する要素の境界矩形情報（left、top、width、height、right、bottom）を取得します。CSS transform変換を考慮します（現在はIDセレクター、クラスセレクターのみサポート）

各ツールは、環境のデフォルト値（プロジェクトパス、CLIパス、WebSocketエンドポイントなど）を上書きするためのオプションの connection ブロックを受け入れます。

使用のヒント

一般的なヒント

• 接続前に、微信開発者ツールで自動化を有効にしてください（設定 → セキュリティ設定 → サービスポート）

• 最初に mp_ensureConnection を呼び出して接続を検証し、システム/ページの詳細を確認することをお勧めします

• WEAPP_AUTOCLOSE=true は、ステートレスな使い捨てのインタラクションに適しています

• ナビゲーション時は常に絶対パスを使用してください（/ で開始）：/pages/mine/mine

• tabBarページには switchTab を、通常のページには navigateTo を使用してください

カスタムコンポーネントの操作

カスタムコンポーネントを操作する場合、2つの方法があります：

方法1：innerSelector パラメータを使用する（推奨）

element_tap、element_input、element_getWxml などのツールに適用されます：

{
  "selector": "#my-component",
  "innerSelector": ".inner-button"
}

• selector：カスタムコンポーネントのセレクター

• innerSelector：コンポーネント内部の要素のセレクター

方法2：要素内クエリツールを使用する

element_getInnerElement および element_getInnerElements に適用されます：

{
  "selector": "#my-component",
  "targetSelector": ".inner-button"
}

制限事項

• page_waitElement はカスタムコンポーネント内部の要素には適用されません。page_waitTimeout と要素クエリツールを組み合わせてポーリングチェックを行ってください。

自動起動機能（AutoLaunch）

WEAPP_AUTOLAUNCH=true を設定すると、MCPサーバーは微信開発者ツールを自動的に検出して起動できます：

1. ポートの自動検出：9420ポートでサービスが実行されているか検出します

2. サービスがない場合は起動：ポートが使用されていない場合、自動的にCLIを呼び出して開発者ツールを起動します

3. プロジェクトの選択：

   • デフォルトのプロジェクト設定がある場合は自動的に使用します

   • デフォルトのプロジェクトがない場合は、最近のプロジェクトをリストアップして選択を促します

   • プロジェクト番号（例：1）または完全なパスの入力をサポートします

設定例

{
  "mcpServers": {
    "weapp-dev": {
      "command": "npx",
      "args": ["-y", "weapp-dev-mcp"],
      "env": {
        "WEAPP_AUTOLAUNCH": "true",
        "WEAPP_PROJECT_PATH": "D:\\path\\to\\your\\project"
      }
    }
  }
}

ワークフロー

1. 初回接続時、WEAPP_AUTOLAUNCH=true を検出

2. 9420ポートにサービスがあるか確認

3. サービスがない場合、自動的に開発者ツールを起動（cli.bat auto --project <path> --auto-port 9420 を使用）

4. 開発者ツールの準備ができるまで45秒待機

5. WebSocket接続を確立

6. 後続の接続は既存の接続を自動的に再利用

ヒント：mp_setDefaultProject を使用してデフォルトプロジェクトを設定すると、次回の接続時に再度プロジェクトを選択する必要はありません。