Whatsapp Desktop

🚀 WhatsApp MCP Server

The WhatsApp MCP (Model Context Protocol) Server is a Node.js-based application that enables you to programmatically interact with the WhatsApp Desktop application installed on macOS through AppleScript automation. You can send messages and check the WhatsApp status without directly operating the WhatsApp user interface.

🚀 Quick Start

1. Download the source code package: Obtain the source code of the project.
2. Extract the package: Unzip the downloaded file.
3. Navigate to the directory: Open the terminal and move to the extracted directory.
4. Install dependencies: Run the command npm install to install necessary packages.
5. Start the service: After successful installation, run npm start in the terminal to start the service.

✨ Features

1. Send Messages to Contacts

Send text messages to specific contacts in your WhatsApp contact list:

• Messages are delivered through the connected WhatsApp Desktop application.
• Support message formatting, including line breaks.
• Use AppleScript to automate the WhatsApp Desktop interface.

2. Check WhatsApp Status (In Development)

Verify whether the WhatsApp application is currently running:

• Return the current running status of WhatsApp.
• Prevent errors when attempting to send messages.

3. List Recent Contacts (In Development)

Due to WhatsApp's privacy protection restrictions, this feature has limited availability:

• Remind users of WhatsApp's privacy limitations.
• Require users to provide the exact contact name for message transmission.

📦 Installation

1. Download the source code package.
2. Extract the file package.
3. Open the terminal and navigate to the extracted directory.
4. Run the command: npm install.
5. After successful installation, run npm start in the terminal to start the service.

💻 Usage Examples

Basic Usage

Send a Message

curl -X POST http://localhost:3000/api/send-message \
     -H "Content-Type: application/json" \
     -d '{"to": "+1234567890", "message": "你好！"}'

Check the Status

curl http://localhost:3000/api/status

Advanced Usage

• Refer to the API documentation in the docs folder at the project root.
• Customize server parameters through the configuration file.
• Use the RESTful API or CLI to call functions.

📚 Documentation

Integration Guide

1. Install and run the WhatsApp MCP Server.
2. Configure the MCP tool settings in Claude Desktop.
3. Add the following content to app-settings.json:

   "mcp.tools.whatsapp": {
     "host": "localhost",
     "port": 3000,
     "timeout": 5000
   }
   

4. Enable the MCP tool plugin in Claude Desktop.

Tool Details

• whatsapp-send-message: Send messages through the WhatsApp Desktop application.
• whatsapp-get-status: Get the current running status of WhatsApp.
• whatsapp-list-contacts: List recently used WhatsApp contacts.

🔧 Technical Details

Tools Used

• @modelcontextprotocol/sdk: MCP Server and stdio transport.
• Zod: Schema validation.
• Node.js built - in modules (child_process, util, fs).
• AppleScript for macOS automation.

Architecture

• Use the Model Context Protocol (MCP) to achieve standardized communication between tools.
• Adopt stdio transport for communication.
• Execute AppleScript commands to interact with the WhatsApp Desktop application.
• Implement comprehensive error logging.

Implementation Details

• Developed with Node.js, supporting an asynchronous non - blocking programming model.
• Based on an event - driven architecture for efficient communication.
• Improve code reusability through modular design.
• Follow standard software development specifications and naming conventions.

Requirements

• Windows, macOS, or Linux operating system.
• Node.js version 14.17.0 or higher.
• npm version 6.0.0 or higher.
• WhatsApp Desktop application installed and logged in.

Limitations

• Only available on macOS systems (depends on AppleScript).
• Requires the WhatsApp Desktop application to be installed and running.
• Affected by WhatsApp UI updates on contact selection.
• Unable to access the full contact list due to privacy protection.
• Can only be used after configuring Claude Desktop.

Security Considerations

• The server interacts with your personal WhatsApp account.
• Messages will be sent from your account and appear as sent by you.
• Only use in a trusted environment.

📄 License

MIT

Disclaimer

This project is not officially supported by WhatsApp Inc. or Meta Platforms, Inc. Please carefully read WhatsApp's terms of service before use and assume the risks on your own.