macOS用 WhatsApp MCP

ClaudeをWhatsAppに接続するためのModel Context Protocolサーバーです。メッセージの読み取り、連絡先の検索、返信の送信をすべて自然な会話で行えます。

機能

• 連絡先の検索 — 名前や電話番号で誰でも検索可能

• メッセージの読み取り — 日付フィルタリングや検索機能付きでチャット履歴を取得

• チャット一覧の表示 — 未読数を含む最近の会話を表示

• メッセージの送信 — Claudeから直接返信（QR認証が必要）

• リアルタイム受信 — メッセージが届くと同時に取得

要件

• macOS（WhatsAppデスクトップアプリがインストールされ、ログイン済みであること）

• Python 3.10+

• Node.js 18+（メッセージ送信に必要）

インストール

pipを使用する場合

pip install whatsapp-mcp-macos

ソースからインストールする場合

git clone https://github.com/kalki-kgp/whatsapp-mcp.git
cd whatsapp-mcp
pip install -e .

Claude Desktopへの接続

1. 設定ファイルを開きます：

   open ~/Library/Application\ Support/Claude/claude_desktop_config.json

   ファイルが存在しない場合は作成してください。

2. WhatsApp MCPサーバーを追加します：

   {
     "mcpServers": {
       "whatsapp": {
         "command": "python3",
         "args": ["-m", "whatsapp_mcp"]
       }
     }
   }

3. Claude Desktopを再起動します（Cmd+Qで終了後、再度開く）

4. チャット入力欄にあるMCPツールアイコン（🔨）を探し、クリックして「whatsapp」がリストに含まれていることを確認します

5. チャットを開始します：

   • 「最近のWhatsAppチャットを表示して」

   • 「夕食の予定に関するメッセージを検索して」

Cursorへの接続

プロジェクト内の .cursor/mcp.json に以下を追加します：

{
  "mcpServers": {
    "whatsapp": {
      "command": "python3",
      "args": ["-m", "whatsapp_mcp"]
    }
  }
}

Cursorを再起動し、AIチャットでWhatsAppツールを使用します。

使用方法

メッセージの読み取り（即時利用可能）

Claudeに話しかけるだけです：

• 「最近のWhatsAppチャットを表示して」

• 「夕食についてのメッセージを検索して」

• 「昨日ジョンは何と言った？」

• 「未読メッセージをまとめて」

メッセージの送信（ブリッジが必要）

1. WhatsAppブリッジを起動します：

   cd bridge && npm install && npm start

2. Claudeに接続状況を確認させます：

   • 「WhatsAppのステータスを確認して」

3. QRコードが表示されたら、ブラウザでデータURLを開き、スマートフォンでスキャンします

4. 接続が完了すると、送信が可能になります：

   • 「お母さんに『遅れる』とメッセージを送って」

   • 「ジョンに『了解』と返信して」

ツール

仕組み

Claude ──MCP──▶ WhatsApp MCP Server
                       │
                       ├──▶ Local SQLite DBs (read messages)
                       │    ~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/
                       │
                       └──▶ WhatsApp Bridge (:3010) ──▶ WhatsApp Web
                            (for sending)

読み取り操作はローカルのWhatsAppデータベースを直接クエリするため、高速でオフラインでも動作します。

送信操作はブリッジを経由します。このブリッジはBaileysを使用してWhatsApp Webに接続します。

開発

# Clone
git clone https://github.com/kalki-kgp/whatsapp-mcp.git
cd whatsapp-mcp

# Install in dev mode
pip install -e ".[dev]"

# Run server
python -m whatsapp_mcp

プライバシー

• すべてのデータはローカルに保持されます。メッセージは自身のWhatsAppデータベースから読み取られます。

• 外部サーバーにはデータは送信されません（送信時のWhatsApp Webを除く）。

• MCPサーバーはマシン上でローカルに実行されます。

ライセンス

MIT