A
securityA
licenseA
qualityA Python server that enables language models like Claude to interact with WhatsApp Business API through GreenAPI, supporting features like sending messages and managing groups.
Last updated -
5
21
MIT License
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-messagetool (requirescontactNameandmessageparameters)Check WhatsApp Status: Verify if the WhatsApp application is running using the
check-whatsapp-statustoolList 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.
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 toolsThis 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
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.
local-only server
The server can only run on the client's local machine because it depends on local resources.
A Node.js application that enables programmatic interaction with WhatsApp desktop on macOS, allowing users to send messages and check WhatsApp status through AppleScript automation without direct UI interaction.
Related MCP Servers
- -securityAlicense-qualityA Node.js application that connects WhatsApp Web with AI models through the Model Context Protocol, enabling automated messaging, contact management, and group chat functionality through AI-driven workflows.Last updated -2132MIT License
- -securityFlicense-qualityA Python server that enables interaction with macOS native applications (Contacts, Notes, Mail, Messages, Reminders, Calendar, and Maps) through AppleScript, featuring asynchronous operations and type-safe interfaces.Last updated -15
- AsecurityAlicenseAqualityProvides a Model Context Protocol server for executing AppleScript and JavaScript for Automation scripts on macOS, featuring a knowledge base of pre-defined scripts and supporting automation of macOS applications and system functions.Last updated -229459MIT License