Content
# 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](https://github.com/modelcontextprotocol/sdk) - MCP server and stdio transport
- [Zod](https://github.com/colinhacks/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
```bash
# 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
```bash
node index.js
```
## Integrating with Claude
To enable Claude to use the WhatsApp MCP server, follow these steps:
1. **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
2. **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:
```json
{
"mcpServers": [
{
"name": "whatsapp-mcp",
"transport": {
"command": "node",
"args": ["path/to/your/index.js"]
}
}
]
}
```
3. **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 WhatsApp
- `message`: Content of the message to send
Example usage (via MCP client):
```javascript
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):
```javascript
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):
```javascript
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.
