WhatsApp MCP Server

WhatsApp MCP サーバー

FastMCP を使用して WhatsApp Business API と連携するための Model Context Protocol (MCP) インターフェースを提供するサーバーです。

はじめに

WhatsApp MCP サーバーは、Claude などの言語モデルが GreenAPI を通じて WhatsApp の機能と連携できるようにする Python 実装です。FastMCP を活用することで、パフォーマンスの向上、開発者体験の改善、よりクリーンな実装を実現しています。

機能

• メッセージング: WhatsApp の連絡先にテキストメッセージを送信
• グループ管理: グループの作成、メンバーの一覧表示、参加者の追加・削除
• セッション処理: WhatsApp API セッションの管理
• チャット履歴: チャット一覧とメッセージ履歴の取得

WhatsApp API クライアント

このプロジェクトは、WhatsApp と連携するために whatsapp-api-client-python ライブラリを使用しています。このクライアントは WhatsApp Cloud API へのアクセスを提供し、利用には GreenAPI アカウントが必要です。

環境変数

このプロジェクトは設定に環境変数を使用します。

• GREENAPI_ID_INSTANCE: あなたの GreenAPI ID インスタンス
• GREENAPI_API_TOKEN: あなたの GreenAPI API トークン

これらは環境内で設定するか、提供されている .env ファイルを使用してください（インストール手順を参照）。

インストール

# Clone the repository
git clone https://github.com/yourusername/whatsapp-mcp-server.git
cd whatsapp-mcp-server

# Install dependencies
pip install -e .

# Set up environment variables
cp .env-template .env
# Edit the .env file with your GreenAPI credentials

使用方法

MCP サーバーを実行します。

# Run the MCP server on default host (127.0.0.1) and port (8000)
whatsapp-mcp

# Specify host and port
whatsapp-mcp --host 0.0.0.0 --port 9000

デバッグ用:

whatsapp-mcp --debug

サーバーは Model Context Protocol (MCP) を使用して通信し、FastMCP で実行すると HTTP または WebSocket 経由でアクセスできます。

利用可能なツール

• open_session: 新しい WhatsApp セッションを開く
• send_message: チャットにメッセージを送信する
• get_chats: チャットの一覧を取得する
• create_group: 新しい WhatsApp グループを作成する
• get_group_participants: グループの参加者を取得する

FastMCP API リファレンス

WhatsApp MCP サーバーは FastMCP を使用して WebSocket と HTTP の両方のエンドポイントを提供します。

• WebSocket: ws://localhost:8000/mcp
• HTTP: http://localhost:8000/mcp

curl などのツールを使用して API を直接テストできます。

# List available tools
curl -X POST http://localhost:8000/mcp/listTools

# Call a tool
curl -X POST http://localhost:8000/mcp/callTool \
  -H "Content-Type: application/json" \
  -d '{"name": "open_session", "arguments": {}}'

Claude Code への追加方法

Claude に WhatsApp サーバーを追加するには、claude mcp add コマンドを使用します。

# Add the WhatsApp MCP server
$ claude mcp add whatsapp -- whatsapp-mcp

# List existing MCP servers - Validate that the server is running
claude mcp list

# Start claude code
claude

Claude での使用

WhatsApp MCP サーバーが実行されると、会話の中で Claude を使用して連携できます。

WhatsApp の認証

Login to WhatsApp

メッセージの送信

Send the "Hello" message to John Doe

Claude Desktop での使用

WhatsApp MCP サーバーを Claude Desktop で使用するには、claude_desktop_config.json ファイルに追加する必要があります。

pip インストールを使用する場合（推奨）

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

実行ファイルを使用する場合

"mcpServers": {
  "whatsapp": {
    "command": "whatsapp-mcp"
  }
}

Docker を使用する場合

"mcpServers": {
  "whatsapp": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "-e", "GREENAPI_ID_INSTANCE=your_instance_id", "-e", "GREENAPI_API_TOKEN=your_api_token", "whatsapp-mcp-server"]
  }
}

Claude Desktop を起動する前に、GreenAPI の認証情報を環境変数または .env ファイルに設定することを忘れないでください。

コマンドラインオプション

WhatsApp MCP サーバーは以下のコマンドライン引数を受け付けます。

• --debug: デバッグ用の詳細レベルを上げます
• --host: サーバーをバインドするホスト（デフォルト: 127.0.0.1）
• --port: サーバーをバインドするポート（デフォルト: 8000）

デバッグ

MCP サーバーをデバッグするには:

• MCP インスペクターを使用する: npx @modelcontextprotocol/inspector whatsapp-mcp
• Claude Desktop のログディレクトリ（通常 macOS では ~/Library/Logs/Claude/）でログを確認する
• http://localhost:8000 で FastMCP の Web インターフェースにアクセスし、対話的な API ドキュメントを参照する

開発

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
flake8 src/

# Run type checking
mypy src/

このプロジェクトはモダンな pyproject.toml 設定を使用しており、以下が含まれています。

• アプリケーションの実行に必要なコア依存関係
• pip install -e ".[dev]" で利用可能な開発用依存関係

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。