WhatsApp MCP（模型上下文协议）服务器是一个 Node.js 应用程序，支持通过编程方式与 macOS 上的 WhatsApp 桌面应用程序进行交互。它使用 AppleScript 自动化功能，提供了一个简单的界面来发送消息和检查 WhatsApp 状态，而无需直接与 WhatsApp UI 交互。
Related MCP server: claude-whatsapp-mcp
向 WhatsApp 联系人列表中的特定联系人发送短信：
消息通过您连接的 WhatsApp 桌面应用程序发送
支持正确的消息格式，包括换行符
使用 AppleScript 实现 WhatsApp 桌面界面自动化
验证 WhatsApp 应用程序当前是否正在运行：
返回 WhatsApp 的当前运行状态
帮助防止尝试发送消息时出现错误
由于 WhatsApp 的隐私保护，此功能提供的功能有限：
告知用户 WhatsApp 的隐私限制
需要准确的联系人姓名才能发送消息
@modelcontextprotocol/sdk - MCP 服务器和 stdio 传输
Zod - 模式验证
Node.js 内置模块（child_process、util、fs）
用于 macOS 自动化的 AppleScript
使用模型上下文协议 (MCP) 进行标准化工具通信
使用 stdio 传输进行通信
执行 AppleScript 命令与 WhatsApp 桌面应用程序进行交互
实现全面的错误日志记录以进行调试
macOS 操作系统
WhatsApp 桌面应用程序已安装
Node.js v14.0.0 或更高版本
互联网连接
# Clone the repository
git clone https://github.com/yourusername/whatsapp-mcp-server.git
# Navigate to the project directory
cd whatsapp-mcp-server
# Install dependencies
npm installnode index.js要让 Claude 使用 WhatsApp MCP 服务器，请按照以下步骤操作：
设置您的 MCP 服务器
按照上述说明安装并配置 WhatsApp MCP 服务器
确保服务器在本地机器上正常运行
使用 MCP 工具配置 Claude Desktop
修改claude_desktop_config.json文件以包含 WhatsApp MCP 工具
该文件通常位于您的 Claude Desktop 应用程序配置目录中
添加以下配置以注册您的 WhatsApp MCP 工具：
{
"mcpServers": [
{
"name": "whatsapp-mcp",
"transport": {
"command": "node",
"args": ["path/to/your/index.js"]
}
}
]
}测试集成
与 Claude 创建测试对话
要求 Claude 向测试联系人发送 WhatsApp 消息
通过 WhatsApp 桌面应用程序验证消息是否已成功发送
向指定的 WhatsApp 联系人发送消息。
参数：
contactName ：WhatsApp 中显示的联系人全名
message ：要发送的消息的内容
使用示例（通过 MCP 客户端）：
const response = await client.invoke("send-whatsapp-message", {
contactName: "John Doe",
message: "Hello, how are you today?"
});检查 WhatsApp 应用程序是否正在运行。
无需任何参数。
使用示例（通过 MCP 客户端）：
const response = await client.invoke("check-whatsapp-status", {});提供有关 WhatsApp 联系人列表隐私限制的信息。
无需任何参数。
使用示例（通过 MCP 客户端）：
const response = await client.invoke("list-recent-contacts", {});服务器使用 AppleScript 来自动化 WhatsApp 桌面应用程序：
激活 WhatsApp 应用程序
使用键盘快捷键导航界面
按姓名搜索联系人
使用向下箭头导航选择联系人
键入并发送消息
全面的错误处理和日志记录：
控制台错误输出
基于文件的日志记录在~/Library/Logs/whatsapp-mcp/
优雅地处理 AppleScript 执行错误
流程级异常处理
将 WhatsApp MCP 工具与 Claude 集成后，您可以使用自然语言指示 Claude 执行以下操作：
提示示例：
“给约翰发一条 WhatsApp 消息，说我将迟到 10 分钟参加会议”
“通过 WhatsApp 向 Sarah 发送以下短信：这是您请求的文件”
“通过 WhatsApp 向妈妈发送‘生日快乐！’”
提示示例：
“WhatsApp 在我的计算机上运行吗？”
“检查 WhatsApp 是否处于活动状态”
“发送消息前验证 WhatsApp 状态”
提示示例：
“你能列出我最近的 WhatsApp 联系人吗？”
“显示我最近在 WhatsApp 上与谁发过消息”
Claude 将根据您的要求使用适当的 MCP 工具并对结果提供反馈。
由于依赖 AppleScript，仅适用于 macOS
需要安装 WhatsApp 桌面应用程序
WhatsApp UI 更改可能会影响联系人选择
由于隐私保护，对 WhatsApp 联系人列表的访问受到限制
需要正确配置 Claude 才能访问本地 MCP 工具
服务器与您的个人 WhatsApp 帐户进行交互
消息从您的帐户发送，并显示为您发送的
仅在受信任的环境中使用
麻省理工学院
该项目与 WhatsApp Inc. 或 Meta Platforms, Inc. 无关。请自行决定使用并遵守 WhatsApp 的服务条款。
Check if WhatsApp is currently running
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool checks if WhatsApp is 'currently running,' which implies a read-only operation, but doesn't disclose behavioral traits like what 'running' means (e.g., process active, logged in), error handling, or performance characteristics. The description is minimal and lacks context beyond the basic purpose.
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?
The description is a single, clear sentence that directly states the tool's purpose without any wasted words. It is appropriately sized and front-loaded, making it easy to understand at a glance.
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?
Given the tool's simplicity (0 parameters, no annotations, no output schema), the description is minimally adequate. It covers the basic purpose but lacks details on behavior, output format, or usage context, which could be helpful for an agent to understand what 'running' entails or how to interpret results.
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?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter details, which is appropriate here, and it doesn't contradict the schema. Baseline is 4 for tools with no parameters, as there's nothing to compensate for.
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?
The description clearly states the action ('Check if') and resource ('WhatsApp'), specifying what the tool does. It distinguishes from siblings like 'send-whatsapp-message' by focusing on status checking rather than messaging, though it doesn't explicitly mention the sibling 'list-recent-contacts'.
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?
No guidance is provided on when to use this tool versus alternatives. The description implies usage for checking WhatsApp's operational status, but it doesn't specify scenarios, prerequisites, or exclusions, such as whether it requires WhatsApp to be installed or configured.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recently contacted people on WhatsApp (simplified)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it lists contacts but doesn't explain what 'recently contacted' means (timeframe, criteria), how results are ordered, or any limitations (e.g., pagination, rate limits). The 'simplified' hint is insufficient to convey operational behavior.
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?
The description is a single, efficient sentence with no wasted words. It's front-loaded with the core purpose ('List recently contacted people on WhatsApp') and uses a brief qualifier ('simplified') that, while vague, doesn't detract from clarity.
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?
Given no annotations and no output schema, the description is incomplete. It lacks details on what 'recently contacted' entails, how results are returned, or any behavioral constraints. For a tool that presumably returns data, more context on output format or limitations is needed.
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?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on the tool's purpose. Baseline is 4 for zero-parameter tools when schema coverage is complete.
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?
The description clearly states the action ('List') and target resource ('recently contacted people on WhatsApp'), making the purpose understandable. It distinguishes from siblings by focusing on listing contacts rather than checking status or sending messages. However, the qualifier 'simplified' is vague and doesn't specify what makes it simplified.
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?
The description implies usage context (WhatsApp contacts) but provides no explicit guidance on when to use this tool versus alternatives. No prerequisites, exclusions, or comparisons to sibling tools are mentioned, leaving the agent to infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message to a contact on WhatsApp
| Name | Required | Description | Default |
|---|---|---|---|
| contactName | Yes | Full name of the contact as it appears in WhatsApp | |
| message | Yes | Message content to send |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but fails to mention critical traits like authentication needs, rate limits, error handling, or whether the message is sent immediately or queued. This leaves significant gaps in understanding the tool's behavior.
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?
The description is a single, efficient sentence that directly states the tool's function without any unnecessary words. It is front-loaded and appropriately sized for a simple tool, making it easy to grasp quickly.
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?
Given the lack of annotations and output schema, the description is incomplete. It doesn't address behavioral aspects like success/error responses, side effects, or integration with sibling tools. For a messaging tool with potential complexities, more context is needed to ensure proper usage.
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?
The schema description coverage is 100%, with clear descriptions for both parameters ('contactName' and 'message'). The description adds no additional meaning beyond the schema, such as formatting details or examples, but the schema adequately documents the parameters, meeting the baseline.
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?
The description clearly states the action ('Send a message') and target ('to a contact on WhatsApp'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'check-whatsapp-status' or 'list-recent-contacts' beyond the obvious functional difference, missing explicit distinction.
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?
No guidance is provided on when to use this tool versus alternatives or any prerequisites. The description lacks context about usage scenarios, such as when to choose this over other messaging methods or if there are limitations like contact availability.
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.
v1.0.0check-whatsapp-status1 field changedInput schema / additionalPropertiesRemoved value: -falselist-recent-contacts1 field changedInput schema / additionalPropertiesRemoved value: -falsecheck-whatsapp-statuslist-recent-contactssend-whatsapp-messageScored across 3 tools
Each tool has a clearly distinct purpose: checking WhatsApp status, listing recent contacts, and sending messages. There is no overlap in functionality, making it easy for an agent to select the correct tool without confusion.
The tools follow a consistent verb-noun pattern with hyphens (e.g., check-whatsapp-status, list-recent-contacts, send-whatsapp-message). However, the use of hyphens instead of underscores is a minor deviation from common snake_case conventions, but it remains readable and predictable.
With only 3 tools, the server feels thin for managing WhatsApp interactions, as it lacks operations like reading messages, managing groups, or handling media. While the tools cover basic actions, the scope is limited, making it borderline appropriate for a comprehensive WhatsApp integration.
The toolset is significantly incomplete for a WhatsApp server, missing essential CRUD operations such as reading incoming messages, replying to messages, managing contacts or groups, and handling attachments. This will likely cause agent failures when trying to perform common WhatsApp tasks beyond the basic ones provided.
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Send WhatsApp messages from your own number, read the replies and send login codes.
I send and manage WhatsApp Web messages through your linked session
Your own WhatsApp as an MCP server: read, search and send from any MCP client.