Whatsapp MCP Ts

🚀 WhatsApp MCP サーバー使用ガイド

このプロジェクトは Node.js ベースの単一プロセスアプリケーションで、WhatsApp Web API に接続し、MCP（Model Context Protocol）サービスを提供することを主な目的としています。以下に、主な機能と技術アーキテクチャを紹介します。

✨ 主な機能

認証管理

• Baileys ライブラリを使用して、WhatsApp アカウントのログインと認証を処理します。
• QR コードのスキャンによる初期ログインと、その後の自動再接続をサポートします。

データ保存

• すべてのチャット履歴、メッセージ内容、およびメタデータは、ローカルの SQLite データベース（パス：./data/whatsapp.db）に保存されます。
• 認証情報や機密データは、./auth_info/ ディレクトリに保存され、バージョン管理システムへの誤送信を防ぎます。

MCP インターフェース

• 複数の MCP ツール関数（連絡先の検索、チャット履歴の一覧表示、メッセージの送信など）を提供します。
• AI クライアント（Claude Desktop や Cursor など）との統合をサポートし、標準入出力を介した対話が可能です。

📦 インストール

1. 環境要件

• Node.js バージョン：23.10.0 以上
• 依存関係のインストール：

npm install

2. サーバーの起動

以下のコマンドを実行して、MCP サービスを起動します。

node src/main.ts

初回起動時には、QR コードのリンクが生成され、コンソールに出力されます。携帯電話でこのリンクをスキャンしてログインを完了してください。

3. AI クライアントの設定

Claude Desktop の場合

• 設定ファイル claude_desktop_config.json を作成します。

{
    "servers": [
      {
        "name": "whatsapp",
        "command": "node",
        "args": ["{{PROJECT_PATH}}/src/main.ts"],
        "stdio": "pipe"
      }
    ]
  }

• {{PROJECT_PATH}} を実際のプロジェクトパスに置き換えてください。

Cursor の場合

• 設定ファイル mcp.json を作成します。

{
    "servers": [
      {
        "name": "whatsapp",
        "command": "node",
        "args": ["{{PROJECT_PATH}}/src/main.ts"],
        "stdio": "pipe"
      }
    ]
  }

4. MCP ツールの使用

AI クライアントで以下のツールを呼び出すことができます。

• searchContacts：連絡先を検索します。
• listChats：最近のチャット履歴を一覧表示します。
• readMessages：メッセージ内容を読み取ります。
• sendMessage：新しいメッセージを送信します。

📚 ドキュメント

トラブルシューティング

QR コードの問題

• QR コードのリンクが自動的に開かない場合は、コンソール出力から URL を取得し、手動でアクセスしてください。
• 携帯電話の WhatsApp アプリで QR コードをスキャンしてログインを完了します。

ログインが無効になった場合

ログインが無効になった場合は、以下の手順を実行してください。

1. 現在実行中の MCP サービスを停止します。
2. ./auth_info/ ディレクトリ内のすべてのファイルを削除します。
3. サービスを再起動し、新しい QR コードのスキャン手順を完了します。

データベースの問題

• SQLite データベースファイルが損傷している場合は、データベースの復元または再構築を試みることができます。
• プロジェクトディレクトリに data/ と auth_info/ フォルダが存在することを確認してください。

ログ記録

プログラムは Pino ライブラリを使用してログを記録し、デフォルトではコンソールに出力されます。Pino のオプションを設定することで、ログレベルと形式を調整できます。

例：

import { log } from 'pino';

const logger = log({ level: 'info' });

logger.info('WhatsApp MCP サービスを起動します');

パラメータ検証

Zod ライブラリを使用して入力パラメータを厳密に検証し、API 呼び出しの安全性と信頼性を確保します。

例：

import { z } from 'zod';

type SendMessageParams = {
  text: string;
};

const validateMessage = z.object({
  text: z.string().min(1)
});

async function sendMessage(params: SendMessageParams) {
  const validated = await validateMessage.parseAsync(params);
  // メッセージを処理する
}

まとめ

この WhatsApp MCP サーバープロジェクトは、開発者に強力なツールセットを提供し、WhatsApp サービスとのやり取りを容易にし、MCP プロトコルを介して AI アプリケーションに統合することができます。このガイドが、このサービスのデプロイと使用をスムーズに行うのに役立つことを願っています。