WhatsApp Web

Automation of Whatsapp Messages without Meta (Business-)API is against WhatsApp' Terms of Service! You take full responsibility for everything you do with this MCP-Server. It is possible that your account will be flagged/restricted.

A Model Context Protocol (MCP) server for WhatsApp Web, implemented in TypeScript. This project is a TypeScript port of the originalwhatsapp-mcprepository.

- TypeScript Implementation: Fully typed codebase for better developer experience and code reliability
- WhatsApp Web Integration: Useswhatsapp-web.jsfor direct connection to WhatsApp Web
- MCP Server: Implements theModel Context Protocolfor seamless integration with AI assistants
- Media Support: Send and receive images, videos, documents, and audio messages
- Multiple Transport Options: Supports stdio and Streamable HTTP transports — even both at once from a single process (start with stdio and setMCP_HTTP_PORTto additionally exposehttp://127.0.0.1:<port>/mcp, or run HTTP-only with--http)
- Flexible Authentication: QR code (as an MCP image tool), pairing code (request_pairing_codetool, or automatically printed to stderr at startup viaWHATSAPP_PAIRING_PHONE_NUMBER), and an optional OAuth flow for HTTP clients (MCP_OAUTH=true) where the browser authorization page shows the WhatsApp QR code — unlinking WhatsApp revokes tokens so clients automatically re-authenticate
- TypeScript MCP Server: Implements the Model Context Protocol to provide standardized tools for AI assistants to interact with WhatsApp
- WhatsApp Web Service: Connects to WhatsApp Web via whatsapp-web.js, handles authentication, and manages message sending/receiving
- Tool Implementations: Provides various tools for contacts, chats, messages, media, and authentication

git clone https://github.com/mario-andreschak/mcp-whatsapp-web.git cd mcp-whatsapp-web

FLUJOprovides a streamlined installation process:
- Navigate to the MCP section in FLUJO
- Click "Add Server"
- Copy and paste this GitHub repository URL:https://github.com/mario-andreschak/mcp-whatsapp-web
- Click "Parse", "Clone, "Install", "Build" and "Update Server"

Important:After starting the server for the first time, you must authenticate with WhatsApp by using theget_qr_codetool and scanning the QR code with your phone. See theAuthenticationsection for detailed instructions.

{ "mcpServers": { "whatsapp": { "command": "node", "args": [ "PATH_TO/dist/index.js" ] } } }

ReplacePATH_TOwith the absolute path to the repository.

Save this asclaude_desktop_config.jsonin your Claude Desktop configuration directory:

- macOS:~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:%APPDATA%\Claude\claude_desktop_config.json
- Linux:~/.config/Claude/claude_desktop_config.json

{ "mcpServers": { "whatsapp": { "command": "node", "args": [ "PATH_TO/dist/index.js" ] } } }

ReplacePATH_TOwith the absolute path to the repository.

Save this asmcp.jsonin your Cursor configuration directory:

- macOS/Linux:~/.cursor/mcp.json
- Windows:%USERPROFILE%\.cursor\mcp.json

The first time you run the server, you'll need to authenticate with WhatsApp:
- Start the MCP server
- Important:You must use theget_qr_codetool to generate a QR code

- In Claude or other AI assistants, explicitly ask to "use the get_qr_code tool to authenticate WhatsApp"
- The assistant will call this tool and display the QR code image

- Open WhatsApp on your phone
- Go to Settings > Linked Devices > Link a Device
- Point your phone camera at the QR code displayed

Your session will be saved locally in thewhatsapp-sessionsdirectory and will be reused automatically on subsequent runs. If you don't authenticate using the QR code, you won't be able to use any WhatsApp functionality.

You can check your current authentication status and manage your session:

- Use thecheck_auth_statustool to verify if you're currently authenticated
- If you need to authenticate with a different WhatsApp account or re-authenticate:
- Use thelogouttool to log out from your current session
- Then use theget_qr_codetool to authenticate with a new QR code

- You want to switch between different WhatsApp accounts
- Your session has expired or been invalidated
- You're experiencing connection issues and need to re-authenticate

- get_qr_code- Get the QR code for WhatsApp Web authentication
- check_auth_status- Check if you're currently authenticated with WhatsApp
- logout- Log out from WhatsApp and clear the current session

- search_contacts- Search for contacts by name or phone number
- get_contact- Get information about a specific contact

- list_chats- List available chats with metadata
- get_chat- Get information about a specific chat
- get_direct_chat_by_contact- Find a direct chat with a specific contact

- list_messages- Retrieve messages with optional filters
- get_message- Get a specific message by ID
- send_message- Send a text message to a chat

- send_file- Send a file (image, video, document) to a chat
- send_audio_message- Send an audio message (voice note)
- download_media- Download media from a message

This MCP server uses Puppeteer to control Chrome browsers for WhatsApp Web connectivity. The server includes a robust browser process management system to prevent orphaned Chrome processes.

- Tracks Chrome browser processes using a PID tracking system
- Cleans up orphaned processes on startup
- Properly closes browser processes during shutdown
- Maintains a record of browser PIDs in.chrome-pids.json

If you notice orphaned Chrome processes that weren't automatically cleaned up, you can use the included cleanup utility:
- Scan for Chrome processes that might be related to WhatsApp Web
- Display a list of potentially orphaned processes
- Ask for confirmation before terminating them
- Clean up the PID tracking file

- src/index.ts- Entry point
- src/server.ts- MCP server implementation
- src/services/whatsapp.ts- WhatsApp Web service
- src/tools/- Tool implementations for various WhatsApp features
- src/types/- TypeScript type definitions
- src/utils/- Utility functions

- npm run build- Build the TypeScript code
- npm run dev- Run in development mode with watch
- npm run lint- Run ESLint
- npm run format- Format code with Prettier
- npm run cleanup-browsers- Detect and clean up orphaned Chrome browser processes
- npm test- Run the unit test suite (fast, no browser needed)
- npm run test:watch- Run unit tests in watch mode during development
- npm run test:e2e- Build, then run end-to-end tests (spawns the real server incl. a headless browser)

- If the QR code doesn't appear, try restarting the server
- If you're already authenticated, no QR code will be shown (usecheck_auth_statusto verify)
- If you need to re-authenticate, use thelogouttool first, then request a new QR code
- WhatsApp limits the number of linked devices; you may need to remove an existing device
- If you receive a message saying "No QR code is currently available," but you're already authenticated, this is normal behavior - usecheck_auth_statusto confirm your authentication status

- Make sure you have a stable internet connection
- If the connection fails, try restarting the server
- Check the logs for detailed error messages

- If you notice high CPU usage or memory consumption, there might be orphaned Chrome processes
- Runnpm run cleanup-browsersto detect and clean up orphaned processes
- If the server crashes frequently, check for orphaned processes and clean them up
- On Windows, you can also use Task Manager to look for multiple Chrome processes with "headless" in the command line
- On Linux/macOS, useps aux | grep chrometo check for orphaned processes

This project is a TypeScript port of the originalwhatsapp-mcpbylharries.

A Salesforce MCP server with automatic integrations for services such as WhatsApp, Slack, email, and custom webhooks.