whatsapp

This MCP server provides programmatic control over the WhatsApp desktop application on macOS using AppleScript. It exposes tools that let you send messages to contacts, check whether WhatsApp is running, and (with limited functionality) reference recent contacts due to privacy protections. Through the MCP protocol, you can invoke the available tools from an MCP client to automate messaging via your local WhatsApp desktop, without manually interacting with the UI.

Available MCP tools include:

• send-whatsapp-message: sends a text message to a specified contact by name. You supply the contactName and the message content.
• check-whatsapp-status: checks if the WhatsApp desktop app is currently running.
• list-recent-contacts: provides information about recent contacts, noting privacy limitations that may affect listing or accuracy. This tool informs the user rather than returning a full contact list.

To use these tools, connect to the MCP server via your MCP client, then invoke the desired tool by name with the required parameters. The server executes AppleScript commands to locate the WhatsApp window, select a contact, and type/send the message, or to verify the process status.

Prerequisites

• macOS with WhatsApp Desktop installed
• Node.js v14.0.0 or higher
• Internet access

Install and run the server locally:

# 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

# Start the server
node index.js

Notes

• Ensure WhatsApp Desktop is installed and logged in on the macOS machine where this server runs.
• The server uses AppleScript to automate WhatsApp; macOS permissions may require you to grant accessibility permissions or approve script execution in System Preferences.
• If you run behind a firewall or via a container, ensure AppleScript automation is permitted and that the host can access the local MCP transport (stdio in this case).

Tips and considerations:

• The AppleScript automation relies on the WhatsApp UI structure; UI changes by WhatsApp could affect reliability.
• The list-recent-contacts tool is WIP and may not return a full contact list due to privacy protections.
• Logs are written to the console and to files under ~/Library/Logs/whatsapp-mcp/ as configured in the server. Check logs if you encounter issues with AppleScript execution.
• If starting via Claude or another client, ensure the MCP transport configuration correctly points to node and the server entry file (index.js).
• For troubleshooting, verify that AppleScript can activate WhatsApp and that the contact name passed to send-whatsapp-message exactly matches the WhatsApp contact name.
• This server is designed for macOS; it will not function on Windows or Linux without a different automation backend.