MCP Whatsapp Web

🚀 MCP WhatsApp Interface

MCP WhatsApp is a minimal console interface for interacting with WhatsApp Web. It allows users to send and receive messages via the command line or by integrating it into other applications. Additionally, it offers a suite of tools for managing and operating WhatsApp accounts.

🚀 Quick Start

Before you start using MCP WhatsApp, make sure you have installed the following dependencies:

npm install puppeteer whatsapp-mcp --save

Initialize a New Project

1. Initialize a new project and add the following to your package.json:

   {
     "name": "whatsapp-bot",
     "version": "1.0.0",
     "scripts": {
       "start": "mcp whatsapp:start"
     },
     "dependencies": {
       "whatsapp-mcp": "^3.0.0",
       "puppeteer": "^20.14.3"
     }
   }
   

2. Create a new startup script src/index.ts:

   import { start } from 'whatsapp-mcp';
   
   start();
   

3. Start the project:

   npm run start
   

✨ Features

1. Low CPU Usage

• Runs in Puppeteer's headless mode to minimize resource consumption.

2. Cross - Platform Compatibility

• Supports Windows, macOS, and Linux systems.

3. High Availability

• Built - in reconnection mechanism to ensure long - term stable operation.

📦 Authentication Process

1. Initialize a New Instance

import { createClient } from 'whatsapp-mcp';

const client = await createClient({
  session: './session',
  headless: true,
  chromiumArgs: ['--no-sandbox', '--disable-gpu']
});

2. Send an Authentication Request

await client.auth.sendQRCode();

3. Handle the Authentication Token

await client.auth.handleAuthResponse('your_auth_token_here');

4. Confirm the Authentication Status

console.log(await client.auth.getStatus());
// Output: { isAuth: true, message: 'Authenticated' }

💻 Usage Examples

Tools Provided

Contact Management

• searchContacts(): Search for contacts by name or phone number.
• getContactById(): Get detailed information about a specific contact.

Chat Management

• listChats(): List all available chats and their metadata.
• getChat(): Get detailed information about a specific chat.
• getDirectChatByContact(): Find a one - on - one chat with a specific contact.

Message Management

• listMessages(): Retrieve messages filtered by conditions.
• sendMessage(): Send text or media messages to a specified target.
• listenForNewMessage(): Subscribe to real - time message notifications.

Media Handling

• Supports sending and receiving multimedia content such as pictures, videos, and files.

Browser Process Management

Headless Mode

You can run the application without displaying the browser window by configuring Puppeteer's headless parameters:

await createClient({
  headless: true,
  ...
});

Automated Resource Cleanup

MCP WhatsApp automatically optimizes memory usage during initialization and cleans up temporary files when the process terminates.

🔧 Technical Details

• Project Structure: By default, session data and cache files are stored in the ./session directory.
• Error Handling: It has a built - in detailed error - catching mechanism to help developers quickly locate issues.
• Logging: Supports outputting debugging information and allows configuration of different logging levels.

🛠️ Troubleshooting

1. Startup Errors

Check if you have a valid WhatsApp account logged in, or try re - initializing the session folder:

rm -rf ./session && npm run start

2. Network Connection Issues

Ensure a stable network and check if the firewall settings block the necessary ports.

📄 License

MCP WhatsApp is released under the MIT License. For detailed license information, please refer to the project repository or the LICENSE file.

For further assistance, please refer to the official documentation or seek support through GitHub Issues.