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