Whatsapp MCP Ts

🚀 WhatsApp MCP Server Usage Guide

This project is a single-process application based on Node.js, primarily used to connect to the WhatsApp Web API and provide MCP (Model Context Protocol) services. Below are its main functions and technical architecture:

🔍 Overview

1. Core Components:
   • Communicate with the WhatsApp Web API using the @whiskeysockets/baileys library.
   • Store messages and chat records in an SQLite database.
   • Provide standard input-output interfaces based on the MCP protocol for AI clients to call.
2. Tech Stack:
   • Development Language: TypeScript
   • Runtime Environment: Node.js (version 23.10.0 and above)
   • Database: SQLite (implemented via the node:sqlite library)
   • Logging: Pino
   • Parameter Validation: Zod

✨ Features

• Authentication Management:
  • Use the Baileys library to handle the login and authentication of WhatsApp accounts.
  • Support scanning QR codes for initial login and subsequent automatic reconnection.
• Data Storage:
  • All chat records, message contents, and metadata are stored in the local SQLite database (path: ./data/whatsapp.db).
  • Authentication information and sensitive data are stored in the ./auth_info/ directory to prevent accidental commits to the version control system.
• MCP Interface:
  • Provide multiple MCP utility functions (e.g., search contacts, list chat records, send messages, etc.).
  • Support integration with AI clients (such as Claude Desktop or Cursor) through standard input-output interaction.

🚀 Quick Start

1. Environment Requirements

• Node.js version: 23.10.0 and above
• Install dependencies:

npm install

2. Start the Server

Run the following command to start the MCP service:

node src/main.ts

When starting for the first time, the program will generate a QR code link and output it in the console. Scan the link with your phone to complete the login.

3. Configure AI Clients

For Claude Desktop:

• Create a configuration file claude_desktop_config.json:

{
    "servers": [
        {
            "name": "whatsapp",
            "command": "node",
            "args": ["{{PROJECT_PATH}}/src/main.ts"],
            "stdio": "pipe"
        }
    ]
}

• Replace {{PROJECT_PATH}} with the actual project path.

For Cursor:

• Create a configuration file mcp.json:

{
    "servers": [
        {
            "name": "whatsapp",
            "command": "node",
            "args": ["{{PROJECT_PATH}}/src/main.ts"],
            "stdio": "pipe"
        }
    ]
}

4. Use MCP Tools

Call the following tools in the AI client:

• searchContacts: Search for contacts.
• listChats: List recent chat records.
• readMessages: Read message contents.
• sendMessage: Send new messages.

🛠️ Troubleshooting

1. QR Code Issues

• If the QR code link cannot be opened automatically, check the console output for the URL and access it manually.
• Scan the QR code with the WhatsApp app on your phone to complete the login.

2. Login Failure

If the login fails, perform the following steps:

1. Stop the currently running MCP service.
2. Delete all files in the ./auth_info/ directory.
3. Restart the service and complete the new QR code scanning process.

3. Database Issues

• If the SQLite database file is corrupted, try to restore or rebuild the database.
• Ensure that the data/ and auth_info/ folders exist in the project directory.

📝 Logging

The program uses the Pino library to record logs, which are output to the console by default. You can adjust the log level and format by configuring the Pino options.

Example:

import { log } from 'pino';

const logger = log({ level: 'info' });

logger.info('Starting the WhatsApp MCP service');

✅ Parameter Validation

Use the Zod library to strictly validate input parameters, ensuring the security and reliability of API calls.

Example:

import { z } from 'zod';

type SendMessageParams = {
    text: string;
};

const validateMessage = z.object({
    text: z.string().min(1)
});

async function sendMessage(params: SendMessageParams) {
    const validated = await validateMessage.parseAsync(params);
    // Process the message
}

📌 Summary

This WhatsApp MCP server project provides developers with a powerful toolset to easily interact with WhatsApp services and integrate them into AI applications through the MCP protocol. We hope this guide helps you successfully deploy and use the service.