WhatsApp Desktop MCP server

This WhatsApp MCP (Model Context Protocol) server enables programmatic interaction with WhatsApp desktop on macOS. It provides a simple interface for sending messages and checking WhatsApp status without manual interaction with the WhatsApp UI, using AppleScript automation to control the desktop application.

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:

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
   • Add the following configuration:

{
  "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

Available MCP Tools

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", {});

Using WhatsApp MCP Tools with Claude

Once integrated, 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"

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

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.