これは、TypeScript で構築され、 @whiskeysockets/baileysライブラリを使用した WhatsApp 用の Model Context Protocol (MCP) サーバーです。
これにより、個人の WhatsApp アカウントを AI エージェント (デスクトップ アプリまたは Cursor 経由の Anthropic Claude など) に接続して、次のことが可能になります。
個人の WhatsApp メッセージを検索します。
連絡先を検索します（グループではなく個人）。
最近のチャットを一覧表示します。
特定のチャットのメッセージ履歴を取得します。
個人またはグループにメッセージを送信します。
WhatsApp WebマルチデバイスAPIを使用して、個人のWhatsAppアカウントに直接接続します。すべてのメッセージと認証情報は、SQLiteデータベース（ ./data/ ）と認証キャッシュ（ ./auth_info/ ）にローカルに保存されます。接続されたAIエージェントにデータが送信されるのは、エージェントがMCPツール（エージェントのインターフェースから制御）を明示的に使用した場合のみです。
（オプション：ここに参照例に類似したスクリーンショットまたは GIF を追加することを検討してください）
ユーザー: WhatsAppで「Meu amor」に「Te amo」というメッセージを送信します
**アシスタント：**わかりました。まずは連絡先を検索する必要があります。使用ツール： whatsapp.search_contacts
{
"query": "Meu amor"
}ツールの結果:
[
{
"jid": "5599xxxxxx@s.whatsapp.net",
"name": "Meu Amor"
}
]**アシスタント：**連絡先が見つかりました。メッセージを送信しています。使用ツール： whatsapp.send_message
{
"recipient": "5599xxxxxx@s.whatsapp.net",
"message": "Te amo"
}ツールの結果:
Message sent successfully to 5599xxxxxx@s.whatsapp.net (ID: XXXXXXXXXXX).Related MCP server: WAHA MCP
サーバーは、接続された AI エージェントに次のツールを公開します。
search_contacts : 名前または電話番号部分 (JID) で連絡先を検索します。
list_messages : ページ区切りを付けて、特定のチャットのメッセージ履歴を取得します。
list_chats : チャットを一覧表示します。アクティビティまたは名前で並べ替え可能で、フィルタリング可能、ページ区切りで、オプションで最後のメッセージの詳細が含まれます。
get_chat : 特定のチャットの詳細情報を取得します。
get_message_context : コンテキストの特定のメッセージ ID の直前と直後に送信されたメッセージを取得します。
send_message : 指定された受信者 JID (ユーザーまたはグループ) にテキスト メッセージを送信します。
Smithery経由で Claude Desktop 用の WhatsApp MCP サーバーを自動的にインストールするには:
npx -y @smithery/cli install @jlucaso1/whatsapp-mcp-ts --client claude**Node.js:**バージョン 23.10.0 以上（ package.jsonに指定）。バージョンはnode -vで確認できます。（TypeScript と SQLite の初期サポートが組み込まれています）
npm (または yarn/pnpm): 通常は Node.js に付属しています。
AI クライアント: Anthropic Claude デスクトップ アプリ、Cursor、Cline、Roo Code (または他の MCP 互換クライアント)。
このリポジトリをクローンします:
git clone <your-repo-url> whatsapp-mcp-ts
cd whatsapp-mcp-ts依存関係をインストールします:
npm install
# or yarn install / pnpm installサーバーを初めて実行します。node node使用してメイン スクリプトを直接実行します。
node src/main.ts初めて実行すると、 quickchart.ioを使用して QR コード リンクが生成され、デフォルトのブラウザーで開こうとします。
WhatsApp モバイル アプリ (設定 > リンクされたデバイス > デバイスのリンク) を使用してこの QR コードをスキャンします。
認証資格情報はauth_info/ディレクトリにローカルに保存されます (これは git では無視されます)。
メッセージの同期が開始され、 ./data/whatsapp.db whatsapp.db に保存されます。履歴のサイズによっては時間がかかる場合があります。進捗状況はwa-logs.txtとコンソール出力でご確認ください。
このターミナルウィンドウは実行したままにしておいてください。同期が完了したら閉じてください。
AI クライアントにこの MCP サーバーを起動する方法を伝える必要があります。
設定JSONを準備します。以下のJSON構造をコピーします。 {{PATH_TO_REPO}}このリポジトリをクローンしたディレクトリへの絶対パスに置き換える必要があります。
{
"mcpServers": {
"whatsapp": {
"command": "node",
"args": [
"{{PATH_TO_REPO}}/src/main.ts"
],
"timeout": 15, // Optional: Adjust startup timeout if needed
"disabled": false
}
}
}**絶対パスを取得するには、**ターミナルでwhatsapp-mcp-tsディレクトリに移動し、 pwdを実行します。この出力を{{PATH_TO_REPO}}として使用します。
設定ファイルを保存します。
Claude Desktop の場合: JSON をclaude_desktop_config.jsonとして構成ディレクトリに保存します。
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json (おそらくパスですが、必要に応じて確認してください)
Linux: ~/.config/Claude/claude_desktop_config.json (おそらくパス。必要に応じて確認してください)
カーソルの場合: JSON をmcp.jsonとして構成ディレクトリに保存します。
~/.cursor/mcp.json
Claude Desktop / Cursorを再起動します。AIクライアントを閉じて再度開きます。これで「whatsapp」MCPサーバーが検出され、ツールが使用できるようになります。
サーバーが起動し（ node src/main.ts経由で手動で起動するか、AIクライアントの設定ファイル経由で起動するかは任意）、AIクライアントに接続されたら、エージェントのチャットインターフェースを介してWhatsAppデータを操作できます。連絡先の検索、最近のチャットの一覧表示、メッセージの閲覧、メッセージの送信などが可能です。
このアプリケーションは、次の機能を備えた単一の Node.js プロセスです。
@whiskeysockets/baileysを使用して WhatsApp Web API に接続し、認証とリアルタイム イベントを処理します。
node:sqliteを使用して、WhatsApp のチャットとメッセージを SQLite データベース ( ./data/whatsapp.db ) にローカルに保存します。
標準入出力 (stdio) を介して AI クライアントからの要求をリッスンする@modelcontextprotocol/sdkを使用して MCP サーバーを実行します。
ローカル SQLite データベースを照会したり、Baileys ソケットを使用してメッセージを送信したりする MCP ツールを提供します。
アクティビティのログ記録にはpinoを使用します (WhatsApp イベントの場合はwa-logs.txt 、MCP サーバー アクティビティの場合はmcp-logs.txt )。
認証: WhatsApp 接続資格情報は./auth_info/ auth_info/ ディレクトリにローカルに保存されます。
**メッセージとチャット:**メッセージ履歴とチャットのメタデータは./data/whatsapp.db whatsapp.db SQLite ファイルにローカルに保存されます。
ローカルデータ: auth_info/とdata/は、誤ってコミットされないように.gitignoreに含まれています。これらのディレクトリは機密情報として扱ってください。
LLMとの連携： AIエージェントがMCPツール（例： list_messages 、 send_message ）のいずれかをアクティブに使用した場合にのみ、接続された大規模言語モデル（LLM）にデータが送信されます。サーバー自体がデータを他の場所に積極的に送信することはありません。
言語: TypeScript
ランタイム: Node.js (>= v23.10.0)
WhatsApp API: @whiskeysockets/baileys
MCP SDK: @modelcontextprotocol/sdk
データベース: node:sqlite (バンドルされた SQLite)
ログ記録: pino
スキーマ検証: zod (MCP ツール入力用)
QR コードの問題:
QR コード リンクが自動的に開かない場合は、コンソール出力でquickchart.io URL を確認し、手動で開きます。
携帯電話の WhatsApp アプリで QR コードをすぐにスキャンしてください。
認証失敗/ログアウト:
接続がDisconnectReason.loggedOutエラーで切断された場合は、再認証が必要です。サーバーを停止し、 ./auth_info/ディレクトリを削除してサーバーを再起動し（ node src/main.ts ）、新しい QR コードを取得してください。
メッセージ同期の問題:
初期同期には時間がかかる場合があります。wa wa-logs.txtでアクティビティを確認してください。
メッセージが同期されていない、または欠落しているように見える場合は、完全なリセットが必要になる可能性があります。サーバーを停止し、 ./auth_info/と./data/の両方のディレクトリを削除してから、サーバーを再起動して再認証を行い、履歴を再同期してください。
MCP 接続の問題 (Claude/Cursor):
claude_desktop_config.jsonまたはmcp.json内のcommandとargs （特に{{PATH_TO_REPO}} ）を再確認してください。パスが絶対パスで正しいことを確認してください。
Node.js が正しくインストールされ、システムの PATH にあることを確認します。
AI クライアントのログで、MCP サーバーの起動に関連するエラーを確認します。
MCP 関連のエラーについては、このサーバーのログ ( mcp-logs.txt ) を確認してください。
メッセージ送信エラー:
受信者の JID が正しいことを確認します (例: ユーザーの場合はnumber@s.whatsapp.net 、グループの場合はgroupid@g.us )。
Baileys からの具体的なエラーについてはwa-logs.txt確認してください。
**一般的な問題:**詳細なエラー メッセージについては、 wa-logs.txtとmcp-logs.txtの両方を確認してください。
MCP 統合に関するさらなる問題については、 公式の MCP ドキュメントを参照してください。
https://github.com/lharries/whatsapp-mcpこのコードベースと同じことを行いますが、go と python を使用します。
このプロジェクトは ISC ライセンスの下でライセンスされています ( package.jsonを参照)。
| Name | Required | Description | Default |
|---|---|---|---|
| chat_jid | Yes | The JID of the chat to retrieve | |
| include_last_message | No | Include last message details (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | The ID of the target message to get context around | |
| before | No | Number of messages before (default 5) | |
| after | No | Number of messages after (default 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max chats per page (default 20) | |
| page | No | Page number (0-indexed, default 0) | |
| sort_by | No | Sort order: 'last_active' (default) or 'name' | last_active |
| query | No | Optional filter by chat name or JID | |
| include_last_message | No | Include last message details (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| chat_jid | Yes | The JID of the chat (e.g., '123456@s.whatsapp.net' or 'group@g.us') | |
| limit | No | Max messages per page (default 20) | |
| page | No | Page number (0-indexed, default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search term for contact name or phone number part of JID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The text content to search for within messages | |
| chat_jid | No | Optional: The JID of a specific chat to search within (e.g., '123...net' or 'group@g.us'). If omitted, searches all chats. | |
| limit | No | Max messages per page (default 10) | |
| page | No | Page number (0-indexed, default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| recipient | Yes | Recipient JID (user or group, e.g., '12345@s.whatsapp.net' or 'group123@g.us') | |
| message | Yes | The text message to send |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_chatget_message_contextlist_chatslist_messagessearch_contactssearch_messagessend_messageScored across 7 tools
The tools are mostly distinct in purpose, with clear separation between chat operations (get_chat, list_chats), message operations (list_messages, search_messages, send_message), and contact operations (search_contacts). However, get_message_context and get_chat could potentially overlap in functionality if both retrieve chat data, creating minor ambiguity.
All tool names follow a consistent verb_noun pattern with snake_case throughout (e.g., get_chat, list_messages, search_contacts). There are no deviations in naming conventions, making the set predictable and readable.
With 7 tools, this server is well-scoped for a WhatsApp integration, covering core functionalities like retrieving chats, messages, contacts, and sending messages. The count is appropriate, neither too sparse nor bloated, allowing comprehensive interaction without overwhelming complexity.
The toolset covers basic read and send operations for chats, messages, and contacts, but lacks update or delete capabilities (e.g., no update_message or delete_chat). This creates notable gaps in lifecycle coverage, though agents can still perform core messaging workflows.
WhatsMCP connects Claude and other MCP-compatible AI agents directly to WhatsApp. Send and receive text, images, documents, and voice notes; manage groups (create, add/remove members, promote admins); look up contacts and profiles; follow channels; and read call and message history — all through a standard MCP interface. For voice use cases, WhatsMCP offers SIP-based calling plans (inbound-only, or full inbound/outbound) so AI voice agents can answer and place WhatsApp calls, plus low-latency WebSocket integrations with voice agent providers like ElevenLabs. Multiple WhatsApp accounts can be paired and managed per workspace, with webhook support for real-time inbound message delivery to your own infrastructure.
Ask questions across your WhatsApp inbox from Claude, ChatGPT, Cursor or any MCP client.
Your own WhatsApp as an MCP server: read, search and send from any MCP client.
Let Claude or ChatGPT search, read and send your WhatsApp messages over MCP. OAuth sign-in.
