wazap-mcp

██╗    ██╗ █████╗ ███████╗ █████╗ ██████╗
██║    ██║██╔══██╗╚══███╔╝██╔══██╗██╔══██╗
██║ █╗ ██║███████║  ███╔╝ ███████║██████╔╝
██║███╗██║██╔══██║ ███╔╝  ██╔══██║██╔═══╝
╚███╔███╔╝██║  ██║███████╗██║  ██║██║
 ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝

あなたのAIエージェントのためのWhatsApp。 WhatsAppアカウント（チャット、メッセージ、メディア、連絡先、グループ）を、任意のMCPクライアントが呼び出せる22のツールの背後に置くMCPサーバーです。ペアリングコードによるログイン、ブラウザ不要、電話番号の再販業者なし、RAM約20MB。

Baileys 上に構築されており、これはWebSocket上でWhatsAppのマルチデバイスプロトコルを話します。

はじめに

npmパッケージは wazap-mcp で、インストールされるコマンドは wazap です。

npx wazap-mcp setup

それがインストールのすべてです。アカウントをリンクし、このマシンにインストールされているMCPクライアントを検出して、それらの設定を書き込み、何を再起動すべきかを教えてくれます。

または、エージェントにやってもらいましょう。これを貼り付けてください：

WhatsAppをセットアップして：npx wazap-mcp setup --agent を実行して、表示される指示に従ってください。

そしてエージェントにこう尋ねます：「今日のWhatsAppで何を見逃した？」

以下は setup が実行する手順です。手動で実行したい場合、それぞれ独立したコマンドとしても使用できます。

npx wazap-mcp login はQRコードを表示します。設定 → リンク済みデバイス → デバイスをリンク からスキャンしてください。カメラが手元にない、またはSSH経由でリンクする場合は？ npx wazap-mcp login --phone +15550100 は、代わりに電話番号でリンク の下に入力する8文字のコードを表示します。最後に、エージェントがメッセージを送信してよいかどうかを尋ねられます。あなたが「はい」と言わない限り答えは「いいえ」で、後で npx wazap-mcp config writes on で変更できます。

npx wazap-mcp connect claude-code は、1つのクライアントのMCPエントリを書き込みます。残りは クライアントを接続 の下の表にあります。

npx wazap-mcp 単体は実行しても安全です。現在の状態と次に何をすべきかを表示し、サーバーは起動しません。何か問題がある場合、npx wazap-mcp status を最初に実行してください。Node、データディレクトリ、ロック、認証情報、新しいバージョンが出ているかどうかを確認し、壊れているものの隣に修正方法を表示します。

クライアントを接続

wazap connect <client> は、ファイル内の他の内容を保持し、最初の変更の前に一度バックアップして、エントリを書き込みます。--dry-run は書き込む内容を表示します。

どのMCPクライアントでも同じように動作します。コマンドは npx -y wazap-mcp、トランスポートは stdio です。エージェントに最初に learn を呼び出すように伝えてください。ID形式、ワークフロー、すべてのエラーコードとその対処法が返されます。

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

Claude Desktop、Cursor、Gemini CLIはまさにそれを受け入れます。VS Codeはそれを servers の下にネストし、command の横に "type": "stdio" を必要とします。Codex CLIはTOMLです：

[mcp_servers.whatsapp]
command = "npx"
args = ["-y", "wazap-mcp"]

skills/ フォルダーは Agent Skills 形式に従っているため、Codex、Cursor、その他のスキル対応エージェントは同じ5つのスキルを読み込めます。

Related MCP server: wa-bridge

ツール

すべてのメッセージには空でない text が付いて返されます。メディアやシステムメッセージには、[image] caption、[voice message]、[deleted]、[poll] Pizza or pasta? のようなプレースホルダーが含まれます。タイムスタンプはマシンのUTCオフセット付きのISO 8601形式で、2h ago のような人間向けの age も併記されます。

スキル

wazapには、ツールだけでなくその背後にあるワークフローをエージェントに教える5つの Agent Skills が同梱されています：

すべて（サーバーとスキル）をClaude Codeプラグインとしてインストール：

/plugin marketplace add razvangirgiz/wazap
/plugin install wazap@wazap

または、skills/<name>/ をエージェントが読み取る任意のスキルディレクトリにコピーします。

エラー

すべての失敗はスタックトレースではなく、構造化された { error, message, fix } として返されます。そのためエージェントは、再試行するか、ユーザーに尋ねるか、停止するかを判断できます。

データディレクトリ

すべては ~/.wazap に置かれます（--data-dir または WAZAP_DATA_DIR で上書き可能）。ディレクトリは 0700 で作成され、認証情報は 0600 で書き込まれます：

~/.wazap/
  auth/         WhatsApp credentials — treat this like a password
  media/        downloads from download_media
  history/      per-chat message history, so a restart is not amnesia
  store.json    chat-list snapshot
  server.lock   pid of the running server
  daemon.json   loopback endpoint a second wazap bridges to
  .env          optional settings, see .env.example

認証情報の書き込みは一時ファイルに行われ、リネームで所定の場所に配置されます。そのため、書き込み途中でプロセスを強制終了しても、電話の再リンクが必要になることはありません。

複数のクライアントを同時に

Claude Desktop、Claude Code、Cursorはそれぞれ独自のwazapを起動します。WhatsAppはリンク済みデバイスごとに1つのソケットしか許可しないため、競合するのではなく1つのセッションを共有します。データディレクトリ上の最初のwazapがセッションを所有し、127.0.0.1上にMCPエンドポイントを開きます。以降に起動するものはすべて、そのエンドポイントを介してブリッジします。設定するものは何もなく、どのクライアントも違いを認識できません。所有者は<data-dir>/daemon.json（0600）に自身のpid、ポート、ブリッジが認証に使うトークンを公開します。

ブリッジは所有者が公開するものをそのまま提供するため、--read-onlyで起動された所有者は、クライアントがどのようなフラグで起動されたかにかかわらず、すべてのクライアントを読み取り専用にします。

所有者が終了するとブリッジも一緒に終了し、クライアントが次に起動するwazapが新しい所有者になります。

WAZAP_NO_SHARE=1でオプトアウトできます。同じディレクトリで2番目のwazapを起動すると、すでに実行中のpidを指定してコード2で終了します。明示的な--httpはブリッジではなく独自のサーバーであり、同じ方法で拒否されます。

読み取り専用モード

書き込みはオプトインです。loginは一度だけ確認し、その回答を<data-dir>/.envに保存します。wazap config writes on|offで変更でき、wazap configだけを実行すると、すべての有効な設定とその出所が表示されます。

WAZAP_READ_ONLY=1またはwazap serve --read-onlyでは、書き込みツールは一切登録されません。エージェントはそれらを認識できないため、誤ってでもあなたの番号から誰かにメッセージを送ることはできません。リンクしたアカウントが個人用の場合に便利です。

書き込みはWAZAP_RATE_LIMIT（デフォルト20、0で無効）により毎分レート制限もされます。人間より速く送信するとアカウントがBANされる原因になります。

HTTPモード

WAZAP_READ_TOKEN=$(openssl rand -hex 32) \
WAZAP_WRITE_TOKEN=$(openssl rand -hex 32) \
npx wazap-mcp serve --http --host 0.0.0.0 --port 8766

/mcpでStreamable HTTP、/healthzでヘルスチェックを提供します。2つのベアラートークンがあります。読み取りトークンは読み取りツールを取得し、書き込みトークンは書き込みツールもロック解除します。したがって、読み取りトークンが漏洩しても誰にもメッセージを送信できません。wazapは、読み取りトークンなしではループバック以外のアドレスへのバインドを拒否します。

セルフホスト

エージェントがノートPC上にない場合（別のマシン、VPS、クライアントのインフラ）は、独自のサーバーでwazapを実行します。セッションはそのサーバー上に留まり、第三者を経由するものはありません。

systemdを使用する場合

npm install -g wazap-mcp
sudo useradd --system --home /var/lib/wazap --create-home wazap
sudo -u wazap WAZAP_DATA_DIR=/var/lib/wazap wazap login --phone +15550100   # pairing code works over SSH
sudo -u wazap tee /var/lib/wazap/.env >/dev/null <<END
WAZAP_READ_TOKEN=$(openssl rand -hex 32)
WAZAP_WRITE_TOKEN=$(openssl rand -hex 32)
END
sudo curl -fsSL https://raw.githubusercontent.com/razvangirgiz/wazap/main/deploy/wazap.service -o /etc/systemd/system/wazap.service
sudo systemctl enable --now wazap
curl -s http://127.0.0.1:8766/healthz

ユニットはループバックのみにバインドします。2行のdeploy/Caddyfile（ホスト名を編集した後caddy run --config deploy/Caddyfile）または任意のリバースプロキシでTLSを前面に配置し、クライアントをAuthorization: Bearer <読み取りまたは書き込みトークン>付きでhttps://your-host/mcpに向けます。

Dockerを使用する場合

git clone https://github.com/razvangirgiz/wazap && cd wazap
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 wazap-data volume
docker compose up -d
curl -s http://127.0.0.1:8766/healthz

コンテナは8766をループバックのみに公開します。前面に同じTLSプロキシを追加します。アップグレードはgit pull && docker compose up -d --buildです。ボリュームがセッションを保持します。

到達できるクライアント

Claude Code、Claude Desktop、Cursor、Codex、VS Code、および「MCP URL + ヘッダー」フィールドを持つ任意のクライアントは、ベアラートークンで接続できます。claude.ai Connectorsは静的トークンではなくOAuthを必要とするため、セルフホストのwazapはまだ使用できません。読み取りのみが必要なクライアントには読み取りトークンを保持し、書き込みトークンは意図的に配布してください。

設定

フラグは環境変数より優先され、環境変数は<data-dir>/.envより優先されます。

既知の制限

• 非公式。 BaileysはWhatsAppのマルチデバイスプロトコルをリバースエンジニアリングしています。これはWhatsApp Business APIではなく、Metaはこれをサポートしていません。

• BANのリスクは現実的です。 自動送信、一括メッセージ、人間がもっともらしく入力しないような操作は番号がBANされる可能性があり、ここから回復することはできません。レート制限は役立ちますが、保証ではありません。

• メディアキーは期限切れになります。 WhatsAppは古い添付ファイルをサーバーから削除するため、古いメッセージに対するdownload_mediaはMEDIA_UNAVAILABLEを返します。

• 履歴は電話が同期するものです。 wazapが参照するのは、WhatsAppがリンク済みデバイスに渡す履歴であり、電話の完全なアーカイブではありません。beforeを指定したread_messagesは、WhatsAppがまだ保持している範囲内でさらに要求します。

• @lid ID。 新しいアカウントは電話番号ではなくプライバシーIDでアドレス指定されます。wazapはマッピングを学習済みの場合は電話番号に変換し直し、未学習の場合は@lidをそのまま渡します。

• 電話が到達可能である必要があります。 リンク済みデバイスは、電話が十分に長くオフラインになると受信を停止します。get_statusはhintでその旨を伝えます。

開発

npm install
npm run typecheck
npm test                       # builds, then runs node --test
node test/smoke-stdio.mjs      # drives the built binary over MCP stdio
npm run dev -- status          # run from source with tsx

npm testはWhatsAppセッションを必要としません。stdioスモークテストは、使い捨てのデータディレクトリに対してビルド済みバイナリを起動し、リンクされていないインストールでもinitialize、tools/list、get_statusに応答することを確認します。

MITライセンス。