WhatsApp MCP Stream

Streamable HTTP トランスポートを中心に構築された WhatsApp MCP サーバーです。WhatsApp への接続には Baileys を使用し、Web 管理 UI と双方向メディアフロー(アップロード + ダウンロード)を備えています。

主な特徴:

• トランスポート: /mcp における Streamable HTTP

• エンジン: Baileys

• 管理 UI: QR、ステータス、ログアウト、ランタイム設定、チャット履歴ビューア

• メディア: アップロード用エンドポイント + /media ホスティング + MCP ダウンロードツール

クイックスタート(Docker)

# build and run

docker compose build

docker compose up -d

サーバーには以下でアクセスできます:

• 管理 UI: http://localhost:3003/admin

• MCP エンドポイント: http://localhost:3003/mcp

• メディアファイル: http://localhost:3003/media/<filename>

Related MCP server: lingtai-whatsapp

--iptables=false を使用するホストの DNS

一部の NAS / 堅牢化されたホスト(例: dockerd --iptables=false の Synology)では、Docker の組込み DNS プロキシ(127.0.0.11)に iptables の DNAT ルールがなく、コンテナ内からの接続が拒否されます。

修正: resolv.conf.example を resolv.conf にコピーし、ボリュームオーバーライドを追加します:

cp resolv.conf.example resolv.conf

次に、ローカルの docker-compose.override.yml(コミット対象外)に追加します:

services:
  mcp-whatsapp:
    volumes:
      - ./resolv.conf:/etc/resolv.conf:ro

docker compose up はオーバーライドを自動的に適用します。

ランタイム設定

設定は管理 UI で編集でき、SETTINGS_PATH(デフォルトは MEDIA_DIR/settings.json)に永続化されます。

管理 UI

ランタイム設定、QR リンク、チャット履歴ビューア、エクスポート、ステータスを備えた管理コンソール。

サポートされている設定:

• media_public_base_url

• upload_max_mb

• upload_enabled

• max_files_per_upload

• require_upload_token

• upload_token

• auto_download_media

• auto_download_max_mb

認証

組み込みの認証はまだ実装されていません。本番環境では、認証を強制するゲートウェイを使用してください。このプロジェクトは authmcp-gateway の背後で問題なく動作します:

https://github.com/loglux/authmcp-gateway

メディアアップロード API

Base64 JSON:

curl -X POST http://localhost:3003/api/upload \
  -H "Content-Type: application/json" \
  -d {filename:photo.jpg,mime_type:image/jpeg,data:<base64>}

Multipart(大きなファイルに推奨):

curl -X POST http://localhost:3003/api/upload-multipart \
  -F "file=@/path/to/file.jpg"

どちらも url と(設定されている場合)publicUrl を返します。

ローカルファイルを send_media で送信する

プロジェクトルートの ./files/ ディレクトリは、コンテナ内の /app/files にバインドマウントされています。そこにファイルを置くと、すぐに参照できます。コンテナの再起動は不要です:

# On host:
cp report.pdf /path/to/whatsapp-mcp-stream/files/

# In send_media:
media_path: /app/files/report.pdf

URL ソースの場合は、media_url を send_media または stage_media に直接渡してください。サーバーが base64 を使わずにファイル自体をダウンロードします。

アップロード認証(オプション)

require_upload_token=true の場合、次のいずれかでトークンを指定します:

• x-upload-token: <token>

• Authorization: Bearer <token>

MCP トランスポート

サーバーは /mcp で Streamable HTTP を公開します。

一般的なフロー:

1. POST /mcp で JSON-RPC の initialize を送信する

2. その後のリクエストには、返された mcp-session-id ヘッダーを使用する

3. ツール呼び出しには POST /mcp を使用する

注: クライアントは initialize の際に Accept: application/json, text/event-stream を送信する必要があります。

スモークテスト

MCP ツールの簡単な回帰スモークテスト:

npm run smoke:mcp

オプションのカスタムターゲット:

MCP_BASE_URL=http://localhost:3003 npm run smoke:mcp

MCP ツール

認証

連絡先

チャット

メッセージ

メディア

ユーティリティ

リカバリノート

このサービスには、Baileys/WhatsApp のセッション状態破損に対する意図的なリカバリ回避策が含まれています。

存在理由:

• 本番環境で、コンテナは生き残って MCP も応答するものの、WhatsApp セッションが機能しないケースが観測されました。

• 最も一般的な兆候は、failed to find key ... to decode mutation や failed to sync state from version といった Baileys エラーでした。

• この状態では、手動でコンテナを再起動するとサービスが復旧することがよくありました。

現在の動作:

• アプリ状態の破損シグナルを受けると、サービスはまず forceResync() によるソフトリカバリを試みます。

• 同じ種類の障害が時間帯内に繰り返される場合は、内部の WhatsApp クライアント再起動にエスカレートされます。

• Connection Terminated などの切断が発生すると、サービスは切断ウォッチドッグをスケジュールし、ソケットが時間内に open に戻らない場合は内部再起動にエスカレートされます。

• 再接続のライフサイクルはネストしたロックデッドロックから保護されているため、手動でのコンテナ再起動を必要とせずに切断からの復旧を完了できます。

• 最近の本番環境の観測では、繰り返されるソケット切断(428 Connection Terminated、503 Stream Errored)が自動的に open に復旧しています。

• 専用の /healthz エンドポイントは、サービスが許容される復旧ウィンドウ外で本当に停止した場合にのみ 503 を返します。

• Docker のヘルスチェックは /healthz を使用するため、コンテナはプロセス内リカバリが動作する機会を持った後にのみ再起動されます。

これらのリカバリメカニズムにより、オペレーターの介入が減り、一般的な WhatsApp/Baileys セッション障害に対する耐性が向上します。

ライセンス

MIT

永続化

チャットとメッセージは、セッションボリュームに保存されるローカル SQLite データベースに永続化されます。

環境変数:

追加のトランスポート診断：

• /mcp POSTリクエストは、logs/mcp-whatsapp.log にリクエストライフサイクルのイベントを記録するようになりました。

• これには、リクエストエントリ、トランスポートのディスパッチ、transport.handleRequest の完了、HTTP の finish / close が含まれます。

• これらのログを使用して、レイテンシ発生がどの段階かを判断します。つまり、レスポンスが whatsapp-mcp-stream を出る前なのか、それともその後にゲートウェイ／クライアント側で発生しているのかを確認できます。

Chat History API

保存済みのチャットとメッセージを参照する方法：

GET /api/chats?limit=50&offset=0&q=<search> — ページングされたチャット一覧（名前によるフィルタリング任意）。

GET /api/chats/:jid/messages?limit=50&offset=0 — チャットのページングされたメッセージ一覧（新しい順）。

どちらのエンドポイントも、管理画面の チャット タブで使用されます。

Export

チャットをエクスポートします（JSON＋任意のダウンロード済みメディア）：

GET /api/export/chat/:jid?include_media=true

include_media=true の場合、ZIPには download_media で既にダウンロード済みのファイルが含まれます。WhatsAppから不足メディアを取得することはありません。