WhatsApp MCP Server

A Model Context Protocol (MCP) server that connects to WhatsApp via Baileys, providing AI with the ability to manage WhatsApp. This is a security-hardened fork of karlfoster/whatsapp-mcp-2.0.

⚠️ WARNING

This project uses the UNOFFICIAL WhatsApp Web API (Baileys). WhatsApp may ban accounts using unofficial clients. USE A DEDICATED BURNER NUMBER — never use your personal number. The authors take no responsibility for account bans or any other consequences of using this software.

What This Is

This is a fork of karlfoster/whatsapp-mcp-2.0 with significant security hardening and operational improvements. It allows an AI assistant (like Claude) to:

• List and search chats, contacts, and messages.

• Send text messages and files (images, videos, documents, audio).

• Download media from received messages.

• Transcribe voice notes via Whisper-compatible APIs.

• Sync phone contacts from VCF files.

Setup

1. Clone the repository:

   git clone <repo-url>
   cd whatsapp-mcp

2. Install dependencies:

   npm ci

3. Configure environment variables: Create a .env file or set them in your MCP client configuration (see below).

4. Run the server:

   npm run dev

5. Scan the QR code: On first run, a QR code will appear in your terminal. Scan it with WhatsApp on your phone: WhatsApp > Settings > Linked Devices > Link a Device

Environment Variables

Storage Locations

• auth_info/: WhatsApp authentication credentials (DO NOT commit).

• data/: SQLite database containing messages, chats, and contacts.

• store/: Baileys message store and .whatsapp.lock file.

• uploads/: Files to send (only files in this directory can be sent via send_file).

• downloads/: Downloaded media files.

• contacts/: VCF files for contact import.

Running Tests

This project uses Vitest for testing.

# Run all tests
npx vitest run

# Run tests with coverage
npx vitest run --coverage

Known Limitations

• No FTS5: SQLite full-text search is not used; substring search (LIKE) is used instead.

• No Read Receipts: The server does not send read receipts.

• No Reactions: Message reactions are not supported.

• No Stories: WhatsApp Stories/Status updates are not accessible.

Security Changes (What changed from upstream)

• Path Traversal Protection: Strict containment checks for send_file and download_media using resolved paths.

• SSRF Validation: WHISPER_API_URL is validated to prevent SSRF attacks (rejects localhost and private IP ranges).

• Atomic Lock File: Prevents multiple instances from connecting to the same WhatsApp account simultaneously.

• Strict Filename Sanitization: All filenames are sanitized to prevent injection and traversal.

• Bounded Memory Caches: Prevents unbounded memory growth in Baileys message retry and device tracking.

• Pre-key Pruning: Automatically prunes old pre-keys to prevent disk bloat.

• Removed reply_spam: Removed the UAE-specific spam reply tool for better general-purpose use.

• Streamed Uploads: send_file uses streams instead of loading full files into memory.

Available Tools

• list_chats: List chats sorted by last activity.

• get_chat: Get chat details with recent messages.

• list_messages: Get messages from a chat.

• search_messages: Substring search across messages.

• search_contacts: Find contacts by name or phone number.

• get_message_context: Get messages surrounding a specific message.

• get_my_profile: Get your own JID and profile info.

• update_contact: Update a contact's display name.

• sync_contacts: Import phone contacts from a VCF file.

• send_message: Send a text message (requires confirmation).

• send_file: Send a media file (requires confirmation).

• delete_message: Delete a message (requires confirmation).

• delete_chat: Delete an entire chat (requires confirmation).

• download_media: Download media from a message to disk.

• transcribe_voice_note: Transcribe a voice note to text.

License

MIT