whatsapp-macos

https://mcp.paperknife.app/ でご確認ください。

macOS 向け WhatsApp MCP

Model Context Protocol サーバーです。Claude を WhatsApp に接続します。Claude に、未読チャットの要約、メッセージ履歴の検索、返信の送信を依頼できます。

読み取りは QR コードのスキャンも Node.js も不要で、約 1 分で使い始められます。送信は任意で、追加の手順が 1 つ必要です。

機能

名前または電話番号で連絡先を検索できます。日付で絞り込んでチャット履歴を読めます。未読数とともに最近の会話を一覧表示できます。まだ読んでいないメッセージをすべて要約できます。ブリッジに接続すると、返信の送信や受信メッセージの取得ができます。

必要条件

• WhatsApp デスクトップアプリがインストールされ、ログイン済みの macOS
• メッセージを送信する場合のみ Node.js 18 以降

Python のインストールは不要です。uvx が適切なバージョンを自動で取得します。

インストール

まだインストールしていない場合は、uv をインストールします。

curl -LsSf https://astral.sh/uv/install.sh | sh

インストールはこれで完了です。初回起動時に uvx がサーバーをダウンロードするため、仮想環境の作成も pip install の手順も必要ありません。次のセクションに進み、Claude からサーバーを利用できるように設定してください。

ソースからのインストール

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

Claude Desktop に接続する

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

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

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

2. uvx のフルパスを確認します。

   which uvx
   

3. WhatsApp MCP サーバーを追加し、コマンドとして上記のパスを貼り付けます。

   {
     "mcpServers": {
       "whatsapp": {
         "command": "/Users/YOU/.local/bin/uvx",
         "args": ["whatsapp-mcp-macos"]
       }
     }
   }
   

   uvx 単体ではなく、絶対パスを使用してください。Claude Desktop は ~/.local/bin を含まない最小限の PATH で起動するため、コマンド名だけを指定するとサーバーが表示されないことがよくあります。

4. Cmd+Q で Claude Desktop を終了してから、再度開きます。ウィンドウを閉じるだけでは不十分です。

5. チャット入力欄の MCP ツールアイコンをクリックし、「whatsapp」が一覧にあることを確認します。

6. チャットを始めます。

   • 「最近の WhatsApp チャットを表示して」
   • 「夕食の予定についてのメッセージを検索して」

Cursor に接続する

プロジェクト内の .cursor/mcp.json に追加します。

{
  "mcpServers": {
    "whatsapp": {
      "command": "/Users/YOU/.local/bin/uvx",
      "args": ["whatsapp-mcp-macos"]
    }
  }
}

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

使い方

メッセージの読み取り（すぐに使えます）

Claude に次のように依頼してください。

• 「最近の WhatsApp チャットを表示して」
• 「夕食についてのメッセージを検索して」
• 「John は昨日何と言っていた？」
• 「未読メッセージを要約して」

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

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

   cd bridge && npm install && npm start
   

2. Claude に接続を確認するよう依頼します。

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

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

4. 接続すると、次のように送信できます。

   • 「遅れると Mom にメッセージを送って」
   • 「John に『いいね』と返信して」

ツール

ツール	説明	ブリッジが必要
whatsapp_status	接続を確認し、必要な場合は QR コードを取得します	いいえ
whatsapp_search_contacts	名前または電話番号で連絡先を検索します	いいえ
whatsapp_list_chats	最近の会話を一覧表示します	いいえ
whatsapp_get_messages	チャットのメッセージを取得します	いいえ
whatsapp_search_messages	すべてのチャットを横断して検索します	いいえ
whatsapp_unread	未読メッセージの概要を取得します	いいえ
whatsapp_send	メッセージを送信します	はい
whatsapp_incoming	リアルタイムで受信メッセージを取得します	はい

仕組み

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