> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP サーバー

> AIエージェントは、GOWAの/mcpに組み込まれたモデルコンテキストプロトコルエンドポイントを介してWhatsAppを使用するようにします。

GOWA は、REST API と同じプロセスから [Model Context Protocol](https://modelcontextprotocol.io) エンドポイントを提供します。**streamable HTTP** トランスポートに対応する MCP クライアントであれば、このエンドポイントを通じてメッセージの送信、チャットの読み取り、グループの管理を行えます。

* URL: `http://<host>:3000<APP_BASE_PATH>/mcp` (デフォルト `http://localhost:3000/mcp`)
* デフォルトで有効になっています。無効にするには、 `MCP_ENABLED=false` または `--mcp-enabled=false` を使用します。
* Stateless: 呼び出し間を生き続けるためのセッションハンドシェイクはありません。

> [!NOTE]
>
> 古いリリースからアップグレードする場合、独立した `./whatsapp mcp` コマンドと、ポート 8080 の SSE エンドポイント（`/sse`）は廃止されています。`./whatsapp rest` を実行し、クライアントの接続先を `/mcp` に設定してください。操作ごとに個別のツールを用意していた従来の構成は、以下の統合ツールに置き換えられました。

## クライアントに接続

`/mcp` は REST API と同じ Basic 認証の後ろに座っています。複数のデバイスを実行する場合は、`Authorization` ヘッダーを送信し、`X-Device-Id` を追加します。

```json theme={null}
{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Basic YWRtaW46Y2hhbmdlbWU=",
        "X-Device-Id": "my-device"
      }
    }
  }
}
```

`YWRtaW46Y2hhbmdlbWU=` は `base64("admin:changeme")`; `echo -n 'user:pass' | base64` であなたのものを生成します。 Basic 認証がオフの場合は `Authorization` を、デバイスが 1 つだけの場合は `X-Device-Id` を省略します。

正確な設定形式はクライアントによって異なります。クライアントが stdio サーバーのみを起動できる場合は、`mcp-remote` などのブリッジを使用します。

## ツール

GOWAは7つのツールを公開します。それぞれのツールは `type` (send) または `action` (全ての他の) 引数をとり、操作を選択します。

| ツール | `type` / `action` value |
| - | - |
| `whatsapp_send` | `text`, `image`, `video`, `audio`, `document`, `sticker`, `location`, `contact`, `poll`, `link`, `forward` |
| `whatsapp_schedule` | `list` 、 `get` 、 `pause` 、 `resume` 、 `cancel` |
| `whatsapp_message` | `react` 、 `edit` 、 `revoke` 、 `delete` 、 `mark_read` 、 `mark_played` 、 `star` 、 `unstar` 、 `download_media` |
| `whatsapp_chat` | `list_chats` 、 `list_contacts` 、 `get_messages` 、 `archive` |
| `whatsapp_group` | `create`, `join_with_link`, `leave`, `info`, `participants`, `add_participants`, `remove_participants`, `promote`, `demote`, `invite_link`, `set_name`, `set_topic`, `set_settings`, `join_requests`, `manage_join_requests` |
| `whatsapp_app` | `status`, `login_qr`, `login_code`, `logout`, `reconnect` |
| `whatsapp_newsletter` | `follow`, `unfollow`, `info`, `directory`, `messages`, `message_updates`, `live_updates_subscribe`, `live_updates_unsubscribe`, `live_updates_list` |

引数に関する注意事項:

* `whatsapp_send` は常に `type` と `phone` を必要とします。メディアは **URL のみで送信されます** (`image_url`, `video_url`, `audio_url`, `file_url`, `sticker_url`); MCP はローカルファイルをアップロードできません。 `link` には `link` と`caption` が必要です。`forward` には `message_id` が必要です。
* `whatsapp_send` は [schedule fields](https://gowa-docs.mintlify.site/ja/examples/scheduled-sends.md) (`scheduled_at`, `timezone`, `recurrence`, `weekdays`, `day_of_month`, `end_at`, `occurrence_limit`)を受け付けます。 `whatsapp_schedule`（`get`、`pause`、`resume`、`cancel`は`schedule_id`）で結果を管理します。
* `whatsapp_message`は`phone`(チャット)と`message_id`;`edit`は`message`も必要です。
* v9.9.0以降の GOWA `main` で、 `whatsapp_message` で `action: "edit"` は `media_type: "image"` または `media_type: "document"` でキャプションを置き換えます。 元のメディアタイプと一致し、`link` を省略します。[Edit a caption](https://gowa-docs.mintlify.site/ja/examples/sending-messages.md#%E7%94%BB%E5%83%8F%E3%81%BE%E3%81%9F%E3%81%AF%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88%E3%81%AE%E3%82%AD%E3%83%A3%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%92%E7%B7%A8%E9%9B%86) を参照してください。
* `whatsapp_chat`: `get_messages`は`chat_jid`; `archive`は`chat_jid`と`archived`を必要とします。
* `whatsapp_app`: `login_code` には `phone` が必要です。

実験的なボタン、位置情報リクエスト、カルーセルの送信は REST でのみ利用できます。[インタラクティブメッセージ](https://gowa-docs.mintlify.site/ja/examples/interactive-messages.md)を参照してください。ニュースレターツールは、チャンネルの検索、履歴のカウンター、自動更新されるライブ更新の購読に対応しています。[ニュースレター](https://gowa-docs.mintlify.site/ja/examples/newsletters.md)を参照してください。

メディア URL のダウンロードは、REST が送信するのと同じパブリックアドレスのチェックを適用し、`HTTP_PROXY` または `HTTPS_PROXY` なしで直接接続します。 ローカルファイルからのアップロードには、REST API が必要です。

MCP クライアントは各ツールの完全な入力スキーマを表示します。HTTP エンドポイントは POST と DELETEを受け付けます。GET SSEストリーミングは無効になります。

## デバイス選択

各通話はこの順序でデバイスを解決します。

1. ツール呼び出しの `device_id` 引数。
2. MCP 接続の `X-Device-Id` ヘッダー。
3. 唯一の登録済みデバイスが存在する場合。

それ以外の場合は `device identification required: set the X-Device-Id header or pass device_id` を渡します。 [Multi-device](https://gowa-docs.mintlify.site/ja/concepts/multidevice.md) を参照してください。

## OAuth を持つリモートクライアント

Claude カスタムコネクタなどのホストされたクライアントは、Basic 認証ヘッダーをアタッチできません。 そのため、GOWAは`/mcp`のOAuth2.1認証サーバーを実行することができます。デフォルトではオフです。

```env theme={null}
APP_BASIC_AUTH=admin:replace-with-a-strong-password
MCP_ENABLED=true
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER_URL=https://gowa.example.com
# optional, defaults to issuer + APP_BASE_PATH + /mcp
MCP_OAUTH_RESOURCE_URL=https://gowa.example.com/mcp
```

要件と行動:

* `APP_BASIC_AUTH` を設定する必要があります。認証ページは同じアカウントのユーザに署名します。起動に失敗します。
* 発行者とリソースは、`http://gowa:3000`のような内部アドレスではなく、クライアントが参照している**パブリックHTTPS** URLでなければなりません。
* OAuth をオンにすると、`/mcp` はベアラートトークンまたは Basic 認証を受け付けます。REST または UI ルートではトークンは受け付けられません。
* クライアントは自分自身を登録します(RFC 7591動的クライアント登録)。登録ボディは16 KiBに制限され、各リダイレクトURIは2 KiBに制限されます。 登録は1時間あたり40と1,000の保存されたクライアントに制限されています。未使用のものは24時間後に削除されます。
* PKCE `S256` は必須です。 コードは5分後に期限切れになり、1時間後にトークンにアクセスします。トークンを更新し、古いものを再利用するとトークンファミリー全体が無効になります。 `MCP_OAUTH_DB_URI` (デフォルトの `file:storages/oauth.db` )には、SHA-256ハッシュのトークンのみが格納されます。

Redirect URI は登録された値と正確に一致する必要があります。ネイティブクライアントは動的ポートでHTTPループバックIPコールバックを使用できます。 `localhost` コールバックは、明示的なポートと完全に一致する必要があります。 他のリダイレクトにはHTTPSが必要です。OAuth `resource` は正規の MCP URLにバインドされます。トークン要求は省略できますが、指定された値が一致する必要があります。 正常に承認された `iss` が含まれます。

期限切れのコードとトークンは、OAuth 書き込み中に削除されます。 更新されたリフレッシュトークンハッシュは、ライブファミリーに対するリプレイを検出するために必要な間、30日間のリフレッシュトークンのライフタイムを最大1回まで維持します。 OAuth データベースを削除または置き換えると、既存のクライアントと助成金が無効になります。

発行者に対するエンドポイント: `/oauth/authorize`, `/oauth/token`, `/oauth/register`. ディスカバリーメタデータはドメインルートでパス挿入よく知られているURLを使用します。そのため`APP_BASE_PATH=/gowa`を使用すると、プロキシはルートする必要があります。

```text theme={null}
https://gowa.example.com/.well-known/oauth-authorization-server/gowa
https://gowa.example.com/.well-known/oauth-protected-resource/gowa/mcp
```

外部からの発見を確認:

```bash theme={null}
curl -i -X POST https://gowa.example.com/mcp          # expect 401 with a Bearer challenge
curl https://gowa.example.com/.well-known/oauth-protected-resource/mcp
curl https://gowa.example.com/.well-known/oauth-authorization-server
```

次に、カスタムコネクタとして `https://gowa.example.com/mcp` を追加し、`APP_BASIC_AUTH` アカウントでサインインします。

> [!WARNING]
>
> GOWAの前にあるCloudflareのアクセス、ボットの課題、または認証プロキシがよく知られている`/oauth/*`または`/mcp`パスを傍受しないようにしてください。 プロキシの `/oauth/authorize` のレート制限に失敗しました。


## Related topics

- [GOWA: WhatsApp REST API](https://gowa-docs.mintlify.site/ja/index.md)
- [サーバーメトリック](https://gowa-docs.mintlify.site/ja/api-reference/metrics.md)
- [whatsappサーバーに再接続](https://gowa-docs.mintlify.site/ja/api-reference/app/whatsappサーバーに再接続.md)
- [Whatsappサーバーにログイン](https://gowa-docs.mintlify.site/ja/api-reference/app/whatsappサーバーにログイン.md)
- [サーバーのメタデータを取得する](https://gowa-docs.mintlify.site/ja/api-reference/app/サーバーのメタデータを取得する.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.