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:

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:

{
  "mcpServers": [
    {
      "name": "whatsapp-mcp",
      "transport": {
        "command": "node",
        "args": ["path/to/your/index.js"]
      }
    }
  ]
}

1. 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):

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.