WhatsApp MCP Server
Overview
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.
Features
1. Send Messages to Contacts
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
2. Check WhatsApp Status (WIP)
Verify if the WhatsApp application is currently running:
- Returns the current running status of WhatsApp
- Helps prevent errors when attempting to send messages
3. List Recent Contacts (WIP)
Due to WhatsApp's privacy protections, this feature provides limited functionality:
- Informs users about WhatsApp's privacy limitations
- Requires exact contact names for messaging
Technical Implementation
Built With
- @modelcontextprotocol/sdk - MCP server and stdio transport
- Zod - Schema validation
- Node.js built-in modules (child_process, util, fs)
- AppleScript for macOS automation
Architecture
- 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
Requirements
- macOS operating system
- WhatsApp desktop application installed
- Node.js v14.0.0 or higher
- Internet connection
Installation
# 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 install
Usage
Starting the Server
node index.js
Integrating with Claude
To 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.jsonfile 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:
- Modify your
{
"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
MCP Tools Available
1. send-whatsapp-message
Sends a message to a specified WhatsApp contact.
Parameters:
contactName: Full name of the contact as it appears in WhatsAppmessage: 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?"
});
2. check-whatsapp-status
Checks if the WhatsApp application is currently running.
No parameters required.
Example usage (via MCP client):
const response = await client.invoke("check-whatsapp-status", {});
3. list-recent-contacts
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", {});
Implementation Details
AppleScript Automation
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
Error Handling
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
Using WhatsApp MCP Tools with Claude
Once you've integrated the WhatsApp MCP tools with Claude, you can use natural language to instruct Claude to:
Send Messages
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"
Check WhatsApp Status
Example prompts:
- "Is WhatsApp running on my computer?"
- "Check if WhatsApp is active"
- "Verify WhatsApp status before sending a message"
Get Contact Information
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.
Limitations
- 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
Security Considerations
- 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
License
MIT
Disclaimer
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.