WhatsApp MCP Server (TypeScript/Baileys)

@jlucaso1

About WhatsApp MCP Server (TypeScript/Baileys)

#nodejs #typescript #ai #mcp #whatsapp #claude

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "whatsapp-mcp-ts": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli",
        "install",
        "@jlucaso1/whatsapp-mcp-ts",
        "--client",
        "claude"
      ]
    }
  }
}

Tools

No tools detected

Fetch the live tool list by running this server in a temporary sandbox using the button above.

Overview

What is WhatsApp MCP Server (TypeScript/Baileys)?

This is an MCP server that connects your personal WhatsApp account to an AI agent. Built with TypeScript and the @whiskeysockets/baileys library, it allows the agent to search messages, contacts, list chats, retrieve chat history, and send messages using the WhatsApp Web multi-device API.

How to use WhatsApp MCP Server (TypeScript/Baileys)?

Clone the repository, install dependencies (npm install), and run node src/main.ts to generate a QR code. Scan it with your WhatsApp mobile app to authenticate. Then configure your AI client (e.g., Claude Desktop or Cursor) with a JSON config pointing to the server's main script. Restart the client to use the server's tools.

Key features of WhatsApp MCP Server (TypeScript/Baileys)

Search contacts by name or phone number.
Retrieve message history with pagination.
List chats, sortable and filterable.
Get detailed information about a specific chat.
Send text messages to individuals or groups.
All data stored locally in SQLite and auth cache.

Use cases of WhatsApp MCP Server (TypeScript/Baileys)

Ask an AI agent to find a conversation and summarize it.
Automatically send reminders or messages to contacts without switching apps.
Analyze chat history for patterns or insights.
Search for a specific contact or message from your personal WhatsApp.
Manage group messages through an AI-powered interface.

FAQ from WhatsApp MCP Server (TypeScript/Baileys)

How does the server connect to my WhatsApp?

It uses the WhatsApp Web multi-device API via the Baileys library. The first run generates a QR code that you scan with your WhatsApp mobile app (Settings > Linked Devices > Link a Device). Authentication credentials are saved locally.

Where is my data stored?

All messages and authentication data are stored locally in your filesystem: authentication info in ./auth_info/ and message history in ./data/whatsapp.db (SQLite). Data is only sent to the AI agent when a tool is explicitly used.

What are the system requirements?

Node.js version 23.10.0 or higher (as specified in package.json). npm is included with Node.js. The server is tested with Anthropic Claude Desktop, Cursor, Cline, or other MCP-compatible clients.

How do I troubleshoot authentication failures?

If the connection logs out (DisconnectReason.loggedOut), stop the server, delete the ./auth_info/ directory, and restart node src/main.ts to get a new QR code. For sync issues, delete both ./auth_info/ and ./data/ directories for a full reset.

What tools does the server expose to the AI agent?

The server provides six MCP tools: search_contacts, list_messages, list_chats, get_chat, get_message_context, and send_message. Each tool is available through the connected AI client's interface.

Frequently asked questions

How does the server connect to my WhatsApp?

Where is my data stored?

All messages and authentication data are stored locally in your filesystem: authentication info in `./auth_info/` and message history in `./data/whatsapp.db` (SQLite). Data is only sent to the AI agent when a tool is explicitly used.

What are the system requirements?

Node.js version 23.10.0 or higher (as specified in `package.json`). npm is included with Node.js. The server is tested with Anthropic Claude Desktop, Cursor, Cline, or other MCP-compatible clients.

How do I troubleshoot authentication failures?

If the connection logs out (DisconnectReason.loggedOut), stop the server, delete the `./auth_info/` directory, and restart `node src/main.ts` to get a new QR code. For sync issues, delete both `./auth_info/` and `./data/` directories for a full reset.

What tools does the server expose to the AI agent?

The server provides six MCP tools: `search_contacts`, `list_messages`, `list_chats`, `get_chat`, `get_message_context`, and `send_message`. Each tool is available through the connected AI client's interface.