Wweb MCP

🚀 WhatsApp Web Bot Framework

A powerful tool for controlling WhatsApp accounts to send and receive messages, based on whatsapp-web.js and connecting via the browser version of WhatsApp.

🚀 Quick Start

📦 Installation

The project uses the npm package manager for dependency management and runtime environment configuration. Install all dependencies:

npm install

🐳 Using Docker

For easy deployment, the project provides a Docker image. Pull the image and start it:

docker pull liuhuanjin0927/whatsapp-web-mcp:latest
docker run -it --rm liuhuanjin0927/whatsapp-web-mcp

💻 Usage Examples

In the main.ts file, you can see a simple running example:

import { WhatsApp } from 'whatsapp-web.js';
import * as WAProto from '@whatsprotypes/core';

async function run() {
    const WA = new WhatsApp({
        puppeteer: {
            executablePath: process.env.CHROME_PATH || undefined,
            args: ['--no-sandbox']
        },
        logLevel: 'info'
    });

    await WA.start();
    console.log('WhatsApp has been started');
}

run().catch(console.error);

✨ Features

• Message Sending and Receiving: Supports sending and receiving text, pictures and other messages.
• Media Handling: Can send and download media content such as pictures, audios, and files.
• Group Management: Provides functions for creating, joining, and leaving group chats.
• Contact Management: Supports adding, deleting, and searching for contacts.
• Logging System: Built - in powerful logging function based on Winston.

📚 Documentation

🔨 Project Building

Build the project from the source code:

npm run build

🧪 Testing

Use Jest for unit testing:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage reports
npm run test:coverage

🎨 Formatting and Code Quality

Use ESLint and Prettier to maintain code specifications:

# Run checks
npm run lint

# Automatically fix issues
npm run lint:fix

# Format the code
npm run format

🔧 Troubleshooting

🛠️ Integration Issues

• Claude Desktop Integration Limitation: Since Claude starts multiple processes, wweb - mcp cannot be directly run in the command - line mode. To solve this problem, we split the application into MCP mode and API mode to achieve compatibility with Claude.

🚧 Future Plans

• Expand Media Support: Support sending videos, audios, and files.
• Template Messages: Provide message templates for common scenarios.
• Advanced Group Features: Enhanced group management features.
• Performance Optimization: Improve the performance of the bot under high load.

🤝 Contribution Guide

📝 How to Contribute Code

1. Fork the project repository.
2. Create a new branch.
3. Commit code changes.
4. Submit a Pull Request.

📋 Development Notes

• Follow the project's code specifications and style.
• Ensure that new features pass unit tests.
• Provide detailed documentation.

📄 Logging

📊 Log Levels

The project supports the following log levels:

• debug: Debug information
• info: General information
• warning: Warning information
• error: Error information
• critical: Severe error
• fatal: Fatal error

The default log level is info.

🛠️ Troubleshooting Guide

❓ Common Issues

1. Unable to connect to the WhatsApp account
   • Make sure the browser is logged in to the target account.
   • Check the network connection status.
   • View the error information output in the console.
2. Docker deployment fails
   • Make sure the Docker service is running.
   • Check the image pulling log.
   • Check the port mapping and permission settings.

👥 Contributors

• Developer: [Your Name]
• Maintainer: [Maintainer's Name]

📄 License

This project is licensed under the MIT License.

Thank you for using the WhatsApp Web Bot Framework! If you have any questions or suggestions, please feel free to contact us.