wazap

╭───────────────╮
│        ▄██▀   │   ██╗    ██╗ █████╗ ███████╗ █████╗ ██████╗
│      ▄██▀     │   ██║    ██║██╔══██╗╚══███╔╝██╔══██╗██╔══██╗
│    ▄███████▀  │   ██║ █╗ ██║███████║  ███╔╝ ███████║██████╔╝
│       ▄██▀    │   ██║███╗██║██╔══██║ ███╔╝  ██╔══██║██╔═══╝
│     ▄█▀       │   ╚███╔███╔╝██║  ██║███████╗██║  ██║██║
╰─╮╭────────────╯    ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝
  ╰╯                WhatsApp for your AI agent.

wazap は、ご自身の WhatsApp アカウント向けの MCP サーバーです。WhatsApp Web と同じようにデバイスとしてリンクし、検出した情報をお使いのマシンに保存して、MCP クライアント（Claude、ChatGPT、Gemini、Cursor、Codex）から、チャット、メッセージ、メディア、連絡先、グループを操作するための 23 個のツールを提供します。

情報を探すために WhatsApp を開く代わりに、次のように尋ねられます。

• 「今日、WhatsApp で何を見逃した？」 — リンク済みのすべてのアカウントを横断して、返事を待っている人、メンション、不在着信、活発なグループの内容をまとめて回答します。
• 「春に Dan が送ってくれた請求書を探して」 — 意味とキーワードの両方で検索し、ファイルを開きます。
• 「ママのボイスメッセージでは何と言ってた？」 — ボイスメッセージをテキストに変換して返します。
• 「Ana に 20 分遅れると伝えて」 — 送信前に、宛先と正確な文面を確認できます。あなたが承認するまで、何も送信されません。

ブラウザーも、ビジネスアカウントも、サードパーティサービスも不要です。wazap のクラウドはありません。お使いの環境で実行されます。

はじめに

Node.js 22 系の 22.16 以降、または 24 以降と、WhatsApp をインストールしたスマートフォンが必要です。

npx wazap-mcp setup

setup はアカウントをリンクし、このマシンにインストールされている MCP クライアント（Claude Code、Claude Desktop、Cursor、Codex、Gemini CLI）を検出して設定を書き込み、クライアントがスキルを読み込む場所に 5 つのスキルをインストールし、再起動が必要なアプリをお知らせします。その後、アシスタントに 「今日、WhatsApp で何を見逃した？」 と尋ねてください。

エージェントに設定を任せたい場合は、次の内容を貼り付けてください。

WhatsApp を設定してください。npx wazap-mcp setup --agent を実行し、表示される手順に従ってください。

ターミナルで npx wazap-mcp を単独で実行しても何も起動しません。現在の状態と次に実行するコマンドが表示されます。問題があるときは、まず npx wazap-mcp status を実行してください。問題のある項目の横に修正方法が表示されます。

クライアントごとの設定

クライアント	最短の方法
Claude Code	/plugin marketplace add razvangirgiz/wazap、次に /plugin install wazap@wazap
Claude Desktop	Releases から wazap-<version>.mcpb をダウンロードし、ダブルクリックします
Cursor	下のバッジをクリックし、npx wazap-mcp skills install cursor を実行します
Codex CLI	npx wazap-mcp connect codex、次に npx wazap-mcp skills install codex を実行します
Gemini CLI	npx wazap-mcp connect gemini を実行します
claude.ai、ChatGPT、その他のホスト型エージェント	OAuth でサインインする URL を使います。リモートアクセスを参照してください
その他	コマンド npx -y wazap-mcp、トランスポート stdio

一般的な JSON を受け付けるクライアント向けの、手動で記述する設定は次のとおりです。

{
  "mcpServers": {
    "whatsapp": { "command": "npx", "args": ["-y", "wazap-mcp"] }
  }
}

setup が行う各手順、connect が書き込む各ファイル、アップグレードについては、docs/install.md を参照してください。

アカウントのリンク

リンクは一度だけ行います。setup が代わりに実行しますが、単独で行う場合は次のとおりです。

npx wazap-mcp login                      # QR code: Settings → Linked devices → Link a device
npx wazap-mcp login --phone +15550100    # pairing code instead, no camera needed

--phone を指定すると、wazap は 8 文字のコードを表示します。スマートフォンで WhatsApp → Settings → Linked devices → Link a device → Link with phone number instead の順に進み、コードを入力してください。このペアリングコードは SSH 経由やヘッドレスサーバーでも使えるため、QR コードの表示が難しい環境でもリンクできます。

アシスタント自身がアカウントをリンクすることもできます。link_account ツールから同じコードが返されるため、Claude Desktop のユーザーがターミナルを使う必要はありません。

1 つの wazap に複数の WhatsApp アカウントを登録できます（wazap account add <id> を実行し、続けて wazap login --account <id> を実行してください）。詳しくは docs/accounts.md を参照してください。

23 個のツール

各引数の意味とすべてのエラーコードについては、docs/tools.md を参照してください。アシスタントは learn を呼び出して、これらすべてを取得します。

ツール	種類	機能
learn	読み取り	すべてのツール、ID 形式、ワークフロー、エラーコードを説明するガイドです。最初に呼び出してください。
get_status	読み取り	接続、同期、リンク済みアカウント、履歴の最新度、Webhook の配信状況、バージョンを確認します。
link_account	読み取り	アシスタントからアカウントをリンクします。スマートフォンに入力する 8 文字のコードが返されます。
list_chats	読み取り	新しい順に会話を表示します。all、unread、groups、individual、archived で絞り込めます。
read_messages	読み取り	1 つのチャットの履歴をさかのぼってページ単位で読み込みます。chat_id: "status" を指定するとストーリーを読み込みます。
catch_up	読み取り	すべてのアカウントを対象に、トークン予算内で 1 回の呼び出しにより「何を見逃したか」を確認します。
search	読み取り	意味と単語の両方でメッセージを検索し、チャット、送信者、日付で絞り込めます。
get_message	読み取り	1 件のメッセージの全情報を取得します。引用、リアクションとその投稿者、投票、配信確認、既読確認を含みます。
find_contact	読み取り	メッセージを作成する前に、「ママ」、ニックネーム、グループ名、または電話番号が誰を指すのかを確認します。
list_contacts	読み取り	スマートフォンのアドレス帳をページ単位で表示します。保存名、電話番号、最後に会話した日時を確認できます。
get_group_info	読み取り	参加者、管理者、グループ設定、管理者用招待リンクを確認します。
get_media	読み取り	音声メモは文字起こしとして、写真は画像として、その他のファイルはディスクに保存して取得します。まず、受信時に保存されたコピーから提供します。
wait_for_messages	読み取り	メッセージが届くまで最大 55 秒間待機します。カーソルを使うため、呼び出し間に届いたメッセージも見逃しません。
remember	ローカル	このマシンにメモ、タグ、人物の詳細を保存します。WhatsApp 上では何も変更されません。
send_message	書き込み	メッセージ、メディア、投票、位置情報、転送を作成しますが、送信はしません。send_at を指定すると、後で送信するメッセージを作成します。
confirm_send	書き込み	ユーザーがプレビューを確認して承認した後、その下書きを 1 回送信します。後で送信する下書きは予約されます。
edit_message	書き込み	WhatsApp の 15 分間の制限内で、自分のメッセージを編集します。
react_to_message	書き込み	絵文字のリアクションを追加または削除します。
delete_message	書き込み	全員から削除します（自分のメッセージ、または自分が管理者であるグループの誰かのメッセージ）。または、このアカウントでのみ削除します。
manage_chat	書き込み	アーカイブ、ピン留め、ミュート、スター、消去、削除、ブロック、取り消しの操作をプレビューします。プレビューを確認すると、1 回適用されます。mark_read は引き続き直接実行されます。
manage_group	書き込み	グループの作成、参加、名前変更、追加、削除、管理者への昇格、招待リンク、参加リクエスト、設定、退出を行います。
scheduled_messages	書き込み	予約済みメッセージ（送信済み、見逃し、失敗も含む）を一覧表示するか、送信前にキャンセルします。
reminder	ローカル	「Ana が 2 日以内に返信しなかったら知らせて」などのリマインダーを設定、一覧表示、キャンセルします。期限になると Webhook に投稿されます。

予約メッセージとリマインダー。 send_at を指定した send_message（Europe/Bucharest での 2026-10-12T09:00 に相当する「tomorrow at 9」）は、後で送信するメッセージを作成します。時刻を含むプレビューにユーザーが承認すると予約され、送信時には送信前の確認がすべて再度実行されます。送信予定時刻から 15 分以内に送信できなかった wazap は、遅れて送信されることなく、見逃しとして報告されます。reminder は「Ana が 2 日以内に返信しなかったら知らせて」というリマインダーを保存し、期限になると Webhook に投稿します。どちらも再起動後も保持されます。メッセージの予約とリマインダーを参照してください。

2 つの機能はデフォルトで無効になっており、どちらも完全にお使いのマシン上で実行できます。 whisper.cpp による音声の文字起こし（docs/voice.md）と、search が単語だけでなく意味でも一致するようにするセマンティック検索（docs/recall.md）です。wazap config transcribe local と wazap config recall local を実行して有効にしてください。

スキル

ツールは何ができるかを示し、skills/ にある 5 つの Agent Skills は、作業をうまく進める方法を示します。

スキル	エージェントが行うこと
whatsapp-inbox	トリアージ：対応が必要／参考情報／ノイズに分類し、返信し忘れたメッセージも確認します。読み取り専用です。
whatsapp-recall	住所、請求書、写真、誰かが言ったことを探します。読み取り専用です。
whatsapp-groups	活発なグループの状況を把握します：決定事項、日付、自分への依頼を確認します。読み取り専用です。
whatsapp-send	相手を特定し、チャット固有の口調で下書きを作成して表示し、承認されたら送信します。
wazap-setup	接続を診断、リンク、または修復します。

setup を実行すると、Claude Code、Codex、Cursor 向けにインストールされます （手動で行う場合は npx wazap-mcp skills install <harness> を実行します）。それ以外のすべてのクライアントには、インストール不要で、サーバーから同じ 5 つが MCP プロンプトとして提供されます。

トランスポート

stdio がデフォルトです。クライアントが npx -y wazap-mcp を起動し、stdin/stdout 経由で通信します。ネットワーク上でリッスンすることはありません。

HTTP（Streamable HTTP）は、クライアントの終了後も稼働し続けるサーバーや、別のマシンからアクセスするサーバー向けです。

npx wazap-mcp serve --http                 # http://127.0.0.1:8766/mcp, health at /healthz

--host／--port（または WAZAP_HOST／WAZAP_PORT）で設定を変更できます。wazap は WAZAP_READ_TOKEN が設定されていない限り、ループバック以外へのバインドを拒否します。クライアントは、静的なベアラートークン（WAZAP_READ_TOKEN、書き込みツールには WAZAP_WRITE_TOKEN も必要）または wazap 自身が提供する OAuth 2.1 で認証します。詳しくはdocs/self-host.mdをご覧ください。

リモートアクセス

次の 2 つのコマンドを使うと、ホスト型エージェントからアクセスできる状態で wazap を稼働し続けられます。

npx wazap-mcp service install   # a launchd agent (macOS) or systemd user unit (Linux)
npx wazap-mcp expose            # a public https URL through Tailscale Funnel or Cloudflare Tunnel

expose は URL と同意用パスワードを表示します。エージェントには URL のみを渡してください。エージェントは自分で登録し、同意ページでは、そのエージェントが読み取り専用か、送信も可能かを選び、パスワードを入力します。詳しくは稼働状態を維持するをご覧ください。

サービスは自動で復旧します。切断されたリンクはバックオフ付きで再試行され、スリープ後に切断された、または応答しなくなったソケットはウォッチドッグが置き換えます。再接続に繰り返し失敗すると wazap は終了し、launchd または systemd が新たに起動します。これらの処理によってリンク済みセッションが削除されることはありません。新たにリンクし直す必要があるのは、WhatsApp でデバイスのリンクを解除した場合のみです。リンクが 5 分間停止したとき、復旧したとき、再リンクが必要になったときに通知を受け取るには、WAZAP_WEBHOOK_EVENTS に alert を含めてください（リンクアラート）。get_status では同じ情報を link の下に表示します。

デプロイ

自分のサーバーで稼働させる場合、セッションがサーバーの外に出ることはありません。Docker を使う場合（amd64 および arm64 向けのイメージは ghcr.io/razvangirgiz/wazap にあります）：

mkdir wazap && cd wazap
curl -fsSLO https://raw.githubusercontent.com/razvangirgiz/wazap/main/docker-compose.yml
printf 'WAZAP_READ_TOKEN=%s\nWAZAP_WRITE_TOKEN=%s\n' $(openssl rand -hex 32) $(openssl rand -hex 32) > .env
docker compose run --rm wazap login --phone +15550100   # once; the session lands in the volume
docker compose up -d
curl -s http://127.0.0.1:8766/healthz

コンテナはポート 8766 をループバックでのみ公開します。前段に TLS を配置してください（deploy/Caddyfileは 2 行です）。systemd ユニットはdeploy/wazap.serviceにあります。どちらのセットアップ、リバースプロキシの信頼設定、OAuth サーバーについても、docs/self-host.mdをご覧ください。独自の製品から wazap を呼び出す方法と、受信メッセージの署名付き Webhook を受け取る方法については、docs/api-and-webhooks.mdをご覧ください。

設定

すべての設定は任意です。環境変数として、プロセスまたは ~/.wazap/.env から読み込まれます（実際の環境変数が優先され、フラグは その両方より優先されます）。手動で編集することはほとんどありません。wazap config で有効な 設定を確認し、変更できます。

設定	デフォルト	説明
WAZAP_DATA_DIR	~/.wazap	認証情報、データベース、モデルの保存場所です（--data-dir も使用できます）。
WAZAP_READ_ONLY	未設定	1 にすると、書き込みツールは登録されません。wazap config writes on|off。
WAZAP_PERSIST_HISTORY	1	0 にすると、再起動後もメッセージをディスクに保存しません。
WAZAP_HOST / WAZAP_PORT	127.0.0.1 / 8766	serve --http の待ち受け先です。
WAZAP_READ_TOKEN / WAZAP_WRITE_TOKEN	未設定	HTTP 用の固定ベアラートークンです。書き込みツールを利用できるのは書き込みトークンのみです。
WAZAP_PUBLIC_URL / WAZAP_OAUTH_PASSWORD	未設定	両方を設定すると、ホスト型エージェント向けの OAuth が有効になります。wazap expose で設定できます。
WAZAP_TRANSCRIBE	off	local（whisper.cpp）または openai（OpenAI 互換 API）を指定します。
WAZAP_RECALL	off	local にすると、ローカルの埋め込みモデルを使ったセマンティック検索が有効になります。
WAZAP_WEBHOOK	off	on にすると、受信メッセージを WAZAP_WEBHOOK_URL に送信します。WAZAP_WEBHOOK_SECRET で署名します。
WAZAP_MEDIA_KEEP	unmuted	到着時にメディアをダウンロードして保持するチャットを指定します。これにより、WhatsApp 側のコピーがなくなった後も get_media を利用できます。選択肢は unmuted、all、chats、off です。上限：WAZAP_MEDIA_KEEP_MAX_MB、WAZAP_MEDIA_KEEP_QUOTA_MB、WAZAP_MEDIA_KEEP_DAYS。

Webhook フィルター、保持するメディアの上限、保持期間、プロキシの信頼設定を含む全項目は docs/settings.md に記載されています。.env.example は 同じ項目をコメント付きで記載したファイルです。

セキュリティとプライバシー

• はいと言わない限り、何も送信されません。 send_message は下書きを作成するだけです。宛先と正確なテキストを返し、ネットワークには接続しません。送信するのは confirm_send のみで、クラッシュした場合も含め、下書きが送信されるのは最大 1 回です。下書きの作成後に確認するのはワークフローであり、同意の証明ではありません。クライアント側で 2 つ目のツールの承認を求めない限り、エージェントは両方のツールを呼び出せます。
• 読み取り専用は実際に機能する切り替えです。 WAZAP_READ_ONLY=1、--read-only、または wazap config writes off を指定すると、書き込みツールは登録されないため、アシスタントが誤ってメッセージを送ることもありません。Claude Desktop バンドルでは、読み取り専用が初期状態で有効になっています。
• 宛先を固定できます。 wazap config send allow +15550100,… でアカウントの送信先を一覧に限定できます。deny を指定すると、名前を指定した宛先への送信を拒否します。どちらも下書きの作成時と送信時に確認されます（docs/send-rules.md）。
• 書き込みにはレート制限があります。 デフォルトではアカウントごとに 1 分あたり 20 件です。人間より速く送信すると、電話番号が利用停止になるためです。
• データはお使いのマシン内にとどまります。 認証情報、メッセージ、メディア、メモは ~/.wazap に保存されます（ディレクトリは 0700、認証情報ファイルは 0600）。アカウントもテレメトリーもありません。マシンの外に送信されるものは、WhatsApp の通信、バージョン確認のための npm レジストリ、文字起こしモデルまたは埋め込みモデルのダウンロード時の Hugging Face、openai を選択した場合に限る文字起こし API、設定した場合のお客様自身の Webhook です（docs/data.md）。
• 一部の人を対象外にできます。 連絡先に #private タグを付けると、アシスタントがその人の名前を指定して尋ねられた場合を除き、その人の発言はすべての対象から除外され、Webhook にも送信されません。#no-catchup を付けると、その人のチャットは catch_up の対象外になります。
• 対応していないこと。 一括送信、スケジューラー、キャンペーンには対応していません。自動で既読にすることはなく、リンクプレビューなしでテキストを送信するため、リンク先のページが取得されることもありません。

脅威モデル、監査での指摘事項、および各項目の制限については、こちらをご覧ください： docs/security-audit.md。

既知の制限事項

• プロトコルは非公式です。 wazap は Baileys を基盤にしています。Baileys は WhatsApp のマルチデバイスプロトコルをリバースエンジニアリングして実装したものです。これは WhatsApp Business API ではなく、Meta のサポート対象でもありません。プロトコルが変更されると、Baileys が追いつくまで wazap が動作しなくなる可能性があります。また、一斉送信したり、送信を希望していない相手にメッセージを送ったりすると、アカウントが制限または禁止される可能性があります。上記の安全対策はこのリスクを軽減しますが、なくすものではありません。リスクはご自身で負うことになります。
• モデルの挙動は Claude でのみ評価しています。 eval/ の評価（58 ケースを各 3 回実行）は Claude で実施しています。他のクライアントにも同じツールとサーバー側の保護機能が適用されますが、それらのモデルがツールをどのように利用するかは評価されていません。ChatGPT 用の手動プロトコルは eval/chatgpt-protocol.md をご覧ください。
• 履歴は、リンク済みデバイスにスマートフォンが同期する内容であり、アーカイブ全体ではありません。 before を指定した read_messages は、WhatsApp がまだ保持している範囲内で、スマートフォンにさらに履歴を要求します。
• 古いメディアは期限切れになります。 WhatsApp は古い添付ファイルをサーバーから削除します。その後、メディアが届いたときに wazap が コピーを保存していない限り、get_media は MEDIA_UNAVAILABLE を返します。デフォルトでは、wazap serve の実行中、ミュートされていないチャットの写真、ボイスメッセージ、音声、ドキュメントを、それぞれ最大 16 MB、合計 1 GB、90 日間保存します。保存されていない間に届いて期限切れになったメディアは復元できません。
• 名前はスマートフォンのアドレス帳から取得します。 WhatsApp がアドレス帳を送信するのは、新しい接続のときだけです。連絡先が電話番号として表示される場合（get_status で contacts_named: 0）、サーバーが動作していない間に wazap contacts resync を実行すると、再取得を要求できます。
• @lid ID。 新しいアカウントではプライバシー ID がアドレスとして使われます。対応関係を取得済みの場合、wazap は電話番号に変換します。
• 通話として表示されるのは WhatsApp 通話のみです。 wazap の停止中に開始して終了した通話は、記録されないことがあります。携帯電話回線の通話は表示されません。
• スマートフォンが接続可能な状態である必要があります。 スマートフォンが長時間オフラインになると、リンク済みデバイスは受信を停止します。その場合は get_status に表示されます。

1.x 系で変更しないことを約束している内容については、docs/stability.md をご覧ください。

ドキュメント

docs/install.md	setup の手順、各クライアント、バックグラウンドサービス、expose、アップグレード、スキル
docs/tools.md	23 個のツールの詳細、ワークフロー、すべてのエラーコード
docs/accounts.md	複数の WhatsApp アカウント、1 台のサーバー上で複数の MCP クライアントを使う方法
docs/voice.md	音声メッセージをテキスト化する方法：ローカルの whisper.cpp、または OpenAI 互換 API
docs/recall.md	ローカルの埋め込みモデルによるセマンティック検索
docs/data.md	データディレクトリ、wazap backup、保持期間、削除済みメッセージと消えるメッセージ
docs/send-rules.md	読み取り専用モード、アカウントごとの送信ルール、レート制限
docs/self-host.md	HTTP モード、systemd、Docker、トンネル、プロキシの信頼設定、OAuth
docs/api-and-webhooks.md	静的トークンによる受信、署名付き Webhook イベントの送信
docs/settings.md	すべての WAZAP_* 設定とそのデフォルト値
docs/security-audit.md	セキュリティ監査
docs/stability.md	1.0 で安定性を保証する内容
CHANGELOG.md	リリースごとの変更履歴

コントリビューション

git clone https://github.com/razvangirgiz/wazap && cd wazap
npm ci
npm run check                  # lint, typecheck, then build and test
node test/smoke-stdio.mjs      # drives the built binary over MCP stdio
npm run dev -- status          # run from source with tsx

テストの実行に WhatsApp アカウントは必要ありません。CLAUDE.md はコントリビューター向けのガイドです。プロジェクトの構成、必ず守るべきルール、リリース手順を記載しています。 github.com/razvangirgiz/wazap から、Issue やプルリクエストをお寄せください。

ライセンス

MIT © Răzvan Girgiz