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

| Variable | Default | Description | | :--- | :--- | :--- | | ALLOWED_SEND_DIR | ./uploads/ | Directory for outbound file sends. | | MAX_SEND_FILE_SIZE | 67108864 (64MB) | Max file size for send_file. | | DOWNLOADS_DIR | ./downloads/ | Directory for downloaded media. | | CONTACTS_DIR | ./contacts/ | Base directory for VCF imports. | | WHISPER_API_URL | (none) | Whisper API endpoint for transcription. | | WHISPER_API_KEY | (none) | API key for Whisper. | | WHISPER_MODEL | whisper-large-v3-turbo | Model name for transcription. | | ZOMBIE_TIMEOUT_MS | 120000 (2min) | Silence before zombie connection detection. | | MAX_SEND_FAILURES | 3 | Consecutive failures before reconnect. | | MIN_SEND_INTERVAL_MS | 3000 (3s) | Minimum delay between sends. | | SEND_JITTER_MS | 2000 (2s) | Random jitter added to send delay. | | MAX_RECONNECT_ATTEMPTS | 10 | Max reconnect attempts before giving up. |

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