MCP WhatsApp Web（TypeScript）

TypeScriptで実装されたWhatsApp Web用のモデルコンテキストプロトコル（MCP）サーバー。このプロジェクトは、オリジナルのwhatsapp-mcpリポジトリのTypeScriptポートです。

この MCP サーバーを使用すると、次のことが可能になります。

個人の WhatsApp メッセージ（メディアを含む）を検索して読む
連絡先を検索する
個人またはグループにメッセージを送信する
メディアファイル（画像、動画、ドキュメント、音声）の送受信

特徴

TypeScript 実装: 開発者エクスペリエンスとコードの信頼性を向上させる、完全に型付けされたコードベース
WhatsApp Web統合: WhatsApp Webへの直接接続にはwhatsapp-web.jsを使用します
MCP サーバー: AI アシスタントとのシームレスな統合を実現するモデルコンテキストプロトコルを実装します。
メディアサポート: 画像、ビデオ、ドキュメント、音声メッセージの送受信
複数のトランスポートオプション:柔軟な統合のためにstdioとSSEトランスポートの両方をサポート

建築

この MCP サーバーは次の要素で構成されています。

TypeScript MCP Server : モデルコンテキストプロトコルを実装し、AIアシスタントがWhatsAppと対話するための標準化されたツールを提供します。
WhatsApp Webサービス: whatsapp-web.jsを介してWhatsApp Webに接続し、認証を処理し、メッセージの送受信を管理します。
ツールの実装: 連絡先、チャット、メッセージ、メディア、認証のためのさまざまなツールを提供します

前提条件

Node.js >= 18.0.0
npmまたはyarn
Chrome/Chromium（Puppeteer が WhatsApp Web 接続に使用）
FFmpeg（オプション、オーディオメッセージの変換用）

インストール

手動インストール

このリポジトリをクローンする
git clone https://github.com/mario-andreschak/mcp-whatsapp-web.git cd mcp-whatsapp-web
依存関係をインストールする
npm install
プロジェクトを構築する
npm run build
環境変数を設定する（オプション）サンプル環境ファイルをコピーし、必要に応じて変更します。
cp .env.example .env
必要に応じて、ログレベルを調整し、FFmpeg へのパスを指定できます。

FLUJOを使用したインストール

FLUJO は合理化されたインストールプロセスを提供します。

FLUJOのMCPセクションに移動します
「サーバーを追加」をクリックします
この GitHub リポジトリの URL をコピーして貼り付けます: https://github.com/mario-andreschak/mcp-whatsapp-web
「解析」、「クローン」、「インストール」、「ビルド」、「サーバーの更新」をクリックします。

FLUJO はクローン作成、依存関係のインストール、ビルドのプロセスを自動的に処理します。

使用法

MCPサーバーの起動

npm start

これにより、デフォルトで stdio トランスポートを使用して MCP サーバーが起動します。これは、Claude Desktop または同様のアプリケーションとの統合に適しています。

**重要：**サーバーの初回起動後、 get_qr_codeツールを使用してQRコードをスマートフォンでスキャンし、WhatsAppで認証する必要があります。詳細な手順については、「認証」セクションをご覧ください。

開発モード

npm run dev

これにより、TypeScript 監視モードと自動サーバー再起動を備えた開発モードでサーバーが起動します。

MCP Inspectorによるデバッグ

npm run debug

MCP Inspectorツールが起動します。このツールは、MCPサーバーのテストとデバッグのためのWebインターフェースを提供します。このツールでは、以下のことが可能です。

利用可能なすべてのツールとそのスキーマを表示する
ツールを直接実行し、その応答を確認する
AIアシスタントに接続せずにサーバーをテストする
デバッグツールの実行と応答の検査

Claudeデスクトップに接続しています

Claude Desktop の設定ファイルを作成します。
{ "mcpServers": { "whatsapp": { "command": "node", "args": [ "PATH_TO/dist/index.js" ] } } }
PATH_TOリポジトリへの絶対パスに置き換えます。
これをclaude_desktop_config.jsonとして Claude Desktop 構成ディレクトリに保存します。
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Claudeデスクトップを再起動します

カーソルに接続

カーソルの設定ファイルを作成します。
{ "mcpServers": { "whatsapp": { "command": "node", "args": [ "PATH_TO/dist/index.js" ] } } }
PATH_TOリポジトリへの絶対パスに置き換えます。
これをカーソル構成ディレクトリにmcp.jsonとして保存します。
- macOS/Linux: ~/.cursor/mcp.json
- Windows: %USERPROFILE%\.cursor\mcp.json
カーソルを再開

認証

サーバーを初めて実行するときには、WhatsApp で認証する必要があります。

MCPサーバーを起動する
重要: QRコードを生成するにはget_qr_codeツールを使用する必要があります
- Claude や他の AI アシスタントでは、「get_qr_code ツールを使用して WhatsApp を認証する」ように明示的に要求します。
- アシスタントはこのツールを呼び出してQRコード画像を表示します
WhatsAppモバイルアプリでQRコードをスキャンします
- 携帯電話でWhatsAppを開きます
- 「設定」>「リンクされたデバイス」>「デバイスをリンク」に移動します
- 表示されたQRコードに携帯電話のカメラを向けます

セッションはwhatsapp-sessionsディレクトリにローカルに保存され、次回の実行時に自動的に再利用されます。QRコードで認証しないと、WhatsAppの機能を一切ご利用いただけません。

認証ステータスとログアウト

現在の認証ステータスを確認し、セッションを管理できます。

check_auth_statusツールを使用して、現在認証されているかどうかを確認します。
別の WhatsApp アカウントで認証したり、再認証したりする必要がある場合:
1. logoutツールを使用して現在のセッションからログアウトします
2. 次に、 get_qr_codeツールを使用して新しいQRコードで認証します。

これは特に次の場合に役立ちます:

異なるWhatsAppアカウントを切り替えたい
セッションが期限切れまたは無効になりました
接続に問題が発生しているため、再認証が必要です

利用可能なMCPツール

認証

get_qr_code - WhatsApp Web認証用のQRコードを取得する
check_auth_status - WhatsAppで現在認証されているかどうかを確認します
logout - WhatsAppからログアウトし、現在のセッションをクリアします

連絡先

search_contacts - 名前または電話番号で連絡先を検索します
get_contact - 特定の連絡先に関する情報を取得する

チャット

list_chats - メタデータを含む利用可能なチャットを一覧表示する
get_chat - 特定のチャットに関する情報を取得する
get_direct_chat_by_contact - 特定の連絡先との直接チャットを見つける

メッセージ

list_messages - オプションのフィルターを使用してメッセージを取得する
get_message - IDで特定のメッセージを取得する
send_message - チャットにテキストメッセージを送信する

メディア

send_file - チャットにファイル（画像、動画、ドキュメント）を送信する
send_audio_message - 音声メッセージ（音声メモ）を送信する
download_media - メッセージからメディアをダウンロードする

ブラウザプロセス管理

このMCPサーバーは、Puppeteerを使用してChromeブラウザを制御し、WhatsApp Web接続を実現します。このサーバーには、孤立したChromeプロセスを防ぐための堅牢なブラウザプロセス管理システムが搭載されています。

自動ブラウザクリーンアップ

サーバーは自動的に次の処理を実行します。

PID追跡システムを使用してChromeブラウザのプロセスを追跡します
起動時に孤立したプロセスをクリーンアップします
シャットダウン時にブラウザのプロセスを適切に閉じます
.chrome-pids.jsonにブラウザ PID の記録を保持します。

手動ブラウザクリーンアップ

自動的にクリーンアップされなかった孤立した Chrome プロセスに気付いた場合は、付属のクリーンアップユーティリティを使用できます。

npm run cleanup-browsers

このユーティリティは次のことを行います。

WhatsApp Webに関連する可能性のあるChromeプロセスをスキャンします
孤立している可能性のあるプロセスのリストを表示する
解雇する前に確認を求める
PID追跡ファイルをクリーンアップする

発達

プロジェクト構造

src/index.ts - エントリポイント
src/server.ts - MCP サーバーの実装
src/services/whatsapp.ts - WhatsApp Web サービス
src/tools/ - WhatsAppのさまざまな機能のためのツール実装
src/types/ - TypeScript 型定義
src/utils/ - ユーティリティ関数

スクリプト

npm run build - TypeScriptコードをビルドする
npm run dev - ウォッチ付きの開発モードで実行
npm run lint - ESLint を実行する
npm run format - Prettier でコードをフォーマットする
npm run cleanup-browsers - 孤立した Chrome ブラウザのプロセスを検出してクリーンアップします

トラブルシューティング

認証の問題

QRコードが表示されない場合は、サーバーを再起動してください。
すでに認証されている場合は、QR コードは表示されません ( check_auth_statusを使用して確認してください)
再認証が必要な場合は、まずlogoutツールを使用してから、新しいQRコードをリクエストしてください。
WhatsAppはリンクできるデバイスの数に制限があるため、既存のデバイスを削除する必要がある場合があります。
「現在QRコードは使用できません」というメッセージが表示されても、すでに認証されている場合は、これは正常な動作ですcheck_auth_statusを使用して認証ステータスを確認してください。

接続の問題

安定したインターネット接続があることを確認してください
接続に失敗した場合は、サーバーを再起動してください
詳細なエラーメッセージについてはログを確認してください

ブラウザプロセスの問題

CPU使用率やメモリ消費量が高い場合は、孤立したChromeプロセスが存在する可能性があります。
npm run cleanup-browsersを実行して孤立したプロセスを検出しクリーンアップします。
サーバーが頻繁にクラッシュする場合は、孤立したプロセスをチェックしてクリーンアップしてください。
Windowsでは、タスクマネージャーを使用して、コマンドラインで「headless」を使用して複数のChromeプロセスを探すこともできます。
Linux/macOSでは、 ps aux | grep chromeを使用して孤立したプロセスを確認します。

ライセンス

マサチューセッツ工科大学

このプロジェクトは、 lharriesによるオリジナルのwhatsapp-mcpの TypeScript ポートです。

Integrations