The WhatsApp MCP Server enables programmatic interaction with the WhatsApp desktop application on macOS via AppleScript automation. With this server, you can:
Send Messages to Contacts: Send text messages to specific contacts using the send-whatsapp-message tool (requires contactName and message parameters)
Check WhatsApp Status: Verify if the WhatsApp application is running using the check-whatsapp-status tool
List Recent Contacts: Retrieve information about recently contacted people, though functionality is limited due to WhatsApp's privacy protections
Leverages macOS-specific AppleScript automation to control the WhatsApp desktop application for sending messages and checking status without direct UI interaction.
Enables programmatic interaction with the WhatsApp desktop application on macOS, allowing for sending messages to contacts and checking the application's status through AppleScript automation.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@WhatsApp MCP Server send a WhatsApp message to Mom saying I'll be home in 30 minutes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The WhatsApp MCP (Model Context Protocol) server is a Node.js application that enables programmatic interaction with the WhatsApp desktop application on macOS. Using AppleScript automation, it provides a simple interface for sending messages and checking WhatsApp status without requiring direct interaction with the WhatsApp UI.
Related MCP server: Zappy MCP
Send text messages to specific contacts in your WhatsApp contact list:
Messages are delivered through your connected WhatsApp desktop application
Supports proper formatting of messages including line breaks
Uses AppleScript to automate the WhatsApp desktop interface
Verify if the WhatsApp application is currently running:
Returns the current running status of WhatsApp
Helps prevent errors when attempting to send messages
Due to WhatsApp's privacy protections, this feature provides limited functionality:
Informs users about WhatsApp's privacy limitations
Requires exact contact names for messaging
@modelcontextprotocol/sdk - MCP server and stdio transport
Zod - Schema validation
Node.js built-in modules (child_process, util, fs)
AppleScript for macOS automation
Uses the Model Context Protocol (MCP) for standardized tool communication
Employs stdio transport for communication
Executes AppleScript commands to interact with the WhatsApp desktop application
Implements comprehensive error logging for debugging
macOS operating system
WhatsApp desktop application installed
Node.js v14.0.0 or higher
Internet connection
# 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.jsTo enable Claude to use the WhatsApp MCP server, follow these steps:
Set up your MCP server
Install and configure the WhatsApp MCP server as described above
Ensure the server is running properly on your local machine
Configure Claude Desktop with your MCP tools
Modify your claude_desktop_config.json file to include the WhatsApp MCP tools
This file is typically located in your Claude Desktop application configuration directory
Add the following configuration to register your WhatsApp MCP tools:
{
"mcpServers": [
{
"name": "whatsapp-mcp",
"transport": {
"command": "node",
"args": ["path/to/your/index.js"]
}
}
]
}Test the Integration
Create a test conversation with Claude
Ask Claude to send a WhatsApp message to a test contact
Verify that the message is sent successfully through the WhatsApp desktop app
Sends a message to a specified WhatsApp contact.
Parameters:
contactName: Full name of the contact as it appears in WhatsApp
message: Content of the message to send
Example usage (via MCP client):
const response = await client.invoke("send-whatsapp-message", {
contactName: "John Doe",
message: "Hello, how are you today?"
});Checks if the WhatsApp application is currently running.
No parameters required.
Example usage (via MCP client):
const response = await client.invoke("check-whatsapp-status", {});Provides information about WhatsApp's privacy limitations for contact listing.
No parameters required.
Example usage (via MCP client):
const response = await client.invoke("list-recent-contacts", {});The server uses AppleScript to automate the WhatsApp desktop application:
Activates the WhatsApp application
Uses keyboard shortcuts to navigate the interface
Searches for contacts by name
Selects contacts using down arrow navigation
Types and sends messages
Comprehensive error handling and logging:
Console error output
File-based logging in ~/Library/Logs/whatsapp-mcp/
Graceful handling of AppleScript execution errors
Process-level exception handling
Once you've integrated the WhatsApp MCP tools with Claude, you can use natural language to instruct Claude to:
Example prompts:
"Send a WhatsApp message to John saying I'll be 10 minutes late for our meeting"
"Message Sarah on WhatsApp with the following text: Here's the document you requested"
"Send 'Happy birthday!' to Mom on WhatsApp"
Example prompts:
"Is WhatsApp running on my computer?"
"Check if WhatsApp is active"
"Verify WhatsApp status before sending a message"
Example prompts:
"Can you list my recent WhatsApp contacts?"
"Show me who I've messaged recently on WhatsApp"
Claude will use the appropriate MCP tool based on your request and provide feedback on the result.
Works only on macOS due to AppleScript dependency
Requires WhatsApp desktop application to be installed
Contact selection may be affected by WhatsApp UI changes
Limited access to WhatsApp's contact list due to privacy protections
Requires proper configuration of Claude to access your local MCP tools
The server interacts with your personal WhatsApp account
Messages are sent from your account and appear as sent by you
Use in trusted environments only
MIT
This project is not affiliated with WhatsApp Inc. or Meta Platforms, Inc. Use at your own discretion and in accordance with WhatsApp's terms of service.
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.
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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
WhatsApp CRM for AI agents: search contacts, read chats, manage the sales pipeline, send messages.
WhatsApp assistants, messaging, broadcasts, and analytics for your iZap account, over OAuth.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/gfb-47/whatsapp-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
