{
  "markdown": "# Very Important\n\nAutomation of Whatsapp Messages without Meta (Business-)API is against WhatsApp' Terms of Service! \nYou take full responsibility for everything you do with this MCP-Server. It is possible that your account will be flagged/restricted.\n\n# MCP WhatsApp Web (TypeScript)\n\nA Model Context Protocol (MCP) server for WhatsApp Web, implemented in TypeScript. This project is a TypeScript port of the original [whatsapp-mcp](https://github.com/lharries/whatsapp-mcp) repository.\n\nWith this MCP server, you can:\n- Search and read your personal WhatsApp messages (including media)\n- Search your contacts\n- Send messages to individuals or groups\n- Send and receive media files (images, videos, documents, audio)\n\n![image](https://github.com/user-attachments/assets/7a28ff03-8f52-40f9-b676-2df1ebae0005)\n![image](https://github.com/user-attachments/assets/105e42c3-2f4d-49cf-9be1-f7d481e5a11b)\n\n\n## Features\n\n- **TypeScript Implementation**: Fully typed codebase for better developer experience and code reliability\n- **WhatsApp Web Integration**: Uses [whatsapp-web.js](https://github.com/pedroslopez/whatsapp-web.js) for direct connection to WhatsApp Web\n- **MCP Server**: Implements the [Model Context Protocol](https://modelcontextprotocol.io/) for seamless integration with AI assistants\n- **Media Support**: Send and receive images, videos, documents, and audio messages\n- **Multiple Transport Options**: Supports stdio and Streamable HTTP transports — even both at once from a single process (start with stdio and set `MCP_HTTP_PORT` to additionally expose `http://127.0.0.1:<port>/mcp`, or run HTTP-only with `--http`)\n- **Flexible Authentication**: QR code (as an MCP image tool), pairing code (`request_pairing_code` tool, or automatically printed to stderr at startup via `WHATSAPP_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\n\n## Architecture\n\nThis MCP server consists of:\n\n1. **TypeScript MCP Server**: Implements the Model Context Protocol to provide standardized tools for AI assistants to interact with WhatsApp\n2. **WhatsApp Web Service**: Connects to WhatsApp Web via whatsapp-web.js, handles authentication, and manages message sending/receiving\n3. **Tool Implementations**: Provides various tools for contacts, chats, messages, media, and authentication\n\n## Prerequisites\n\n- Node.js >= 20.0.0\n- npm or yarn\n- Google Chrome or Microsoft Edge (auto-detected; only needed for sending videos/GIFs — everything else works with the Chromium that puppeteer downloads automatically)\n\nFFmpeg is bundled automatically via the `ffmpeg-static` npm package — no manual installation needed. You can point the `FFMPEG_PATH` environment variable at your own binary to override it.\n\n## Installation\n\n### Manual Installation\n\n1. **Clone this repository**\n\n   ```bash\n   git clone https://github.com/mario-andreschak/mcp-whatsapp-web.git\n   cd mcp-whatsapp-web\n   ```\n\n2. **Install dependencies**\n\n   ```bash\n   npm install\n   ```\n\n3. **Build the project**\n\n   ```bash\n   npm run build\n   ```\n\n4. **Configure environment variables (optional)**\n\n   Copy the example environment file and modify as needed:\n\n   ```bash\n   cp .env.example .env\n   ```\n\n   You can adjust logging levels, pin the WhatsApp Web version, or override the auto-detected browser (`BROWSER_EXECUTABLE_PATH`) and ffmpeg binary (`FFMPEG_PATH`) if needed. `WHATSAPP_HEADLESS=false` shows the browser window (debugging aid), and `WHATSAPP_SESSION_DIR` relocates the session/browser-profile directory (useful for running multiple instances or isolated test runs).\n\n### Installation with FLUJO\n\n[FLUJO](https://github.com/mario-andreschak/FLUJO/) provides a streamlined installation process:\n\n1. Navigate to the MCP section in FLUJO\n2. Click \"Add Server\"\n3. Copy and paste this GitHub repository URL: `https://github.com/mario-andreschak/mcp-whatsapp-web`\n4. Click \"Parse\", \"Clone, \"Install\", \"Build\" and \"Update Server\"\n\nFLUJO will automatically handle the cloning, dependency installation, and building process for you.\n\n## Usage\n\n### Starting the MCP Server\n\n```bash\nnpm start\n```\n\nThis will start the MCP server using stdio transport by default, which is suitable for integration with Claude Desktop or similar applications.\n\n> **Important:** After starting the server for the first time, you must authenticate with WhatsApp by using the `get_qr_code` tool and scanning the QR code with your phone. See the [Authentication](#authentication) section for detailed instructions.\n\n### Development Mode\n\n```bash\nnpm run dev\n```\n\nThis starts the server in development mode with TypeScript watch mode and automatic server restarts.\n\n### Debugging with MCP Inspector\n\n```bash\nnpm run debug\n```\n\nThis launches the MCP Inspector tool, which provides a web interface for testing and debugging your MCP server. The inspector allows you to:\n\n- View all available tools and their schemas\n- Execute tools directly and see their responses\n- Test your server without needing to connect it to an AI assistant\n- Debug tool execution and inspect responses\n\n### Connecting to Claude Desktop\n\n1. Create a configuration file for Claude Desktop:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"whatsapp\": {\n         \"command\": \"node\",\n         \"args\": [\n           \"PATH_TO/dist/index.js\"\n         ]\n       }\n     }\n   }\n   ```\n\n   Replace `PATH_TO` with the absolute path to the repository.\n\n2. Save this as `claude_desktop_config.json` in your Claude Desktop configuration directory:\n\n   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n   - Linux: `~/.config/Claude/claude_desktop_config.json`\n\n3. Restart Claude Desktop\n\n### Connecting to Cursor\n\n1. Create a configuration file for Cursor:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"whatsapp\": {\n         \"command\": \"node\",\n         \"args\": [\n           \"PATH_TO/dist/index.js\"\n         ]\n       }\n     }\n   }\n   ```\n\n   Replace `PATH_TO` with the absolute path to the repository.\n\n2. Save this as `mcp.json` in your Cursor configuration directory:\n\n   - macOS/Linux: `~/.cursor/mcp.json`\n   - Windows: `%USERPROFILE%\\.cursor\\mcp.json`\n\n3. Restart Cursor\n\n## Authentication\n\nThe first time you run the server, you'll need to authenticate with WhatsApp:\n\n1. Start the MCP server\n2. **Important:** You must use the `get_qr_code` tool to generate a QR code\n   - In Claude or other AI assistants, explicitly ask to \"use the get_qr_code tool to authenticate WhatsApp\"\n   - The assistant will call this tool and display the QR code image\n3. Scan the QR code with your WhatsApp mobile app\n   - Open WhatsApp on your phone\n   - Go to Settings > Linked Devices > Link a Device\n   - Point your phone camera at the QR code displayed\n\nYour session will be saved locally in the `whatsapp-sessions` directory 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.\n\n### Authentication Status and Logout\n\nYou can check your current authentication status and manage your session:\n\n- Use the `check_auth_status` tool to verify if you're currently authenticated\n- If you need to authenticate with a different WhatsApp account or re-authenticate:\n  1. Use the `logout` tool to log out from your current session\n  2. Then use the `get_qr_code` tool to authenticate with a new QR code\n\nThis is particularly useful when:\n- You want to switch between different WhatsApp accounts\n- Your session has expired or been invalidated\n- You're experiencing connection issues and need to re-authenticate\n\n## Available MCP Tools\n\n### Authentication\n- `get_qr_code`- Get the QR code for WhatsApp Web authentication\n- `check_auth_status`- Check if you're currently authenticated with WhatsApp\n- `logout`- Log out from WhatsApp and clear the current session\n\n### Contacts\n- `search_contacts`- Search for contacts by name or phone number\n- `get_contact`- Get information about a specific contact\n\n### Chats\n- `list_chats`- List available chats with metadata\n- `get_chat`- Get information about a specific chat\n- `get_direct_chat_by_contact`- Find a direct chat with a specific contact\n\n### Messages\n- `list_messages`- Retrieve messages with optional filters\n- `get_message`- Get a specific message by ID\n- `send_message`- Send a text message to a chat\n\n### Media\n- `send_file`- Send a file (image, video, document) to a chat\n- `send_audio_message`- Send an audio message (voice note)\n- `download_media`- Download media from a message\n\n## Browser Process Management\n\nThis 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.\n\n### Automatic Browser Cleanup\n\nThe server automatically:\n- Tracks Chrome browser processes using a PID tracking system\n- Cleans up orphaned processes on startup\n- Properly closes browser processes during shutdown\n- Maintains a record of browser PIDs in `.chrome-pids.json`\n\n### Manual Browser Cleanup\n\nIf you notice orphaned Chrome processes that weren't automatically cleaned up, you can use the included cleanup utility:\n\n```bash\nnpm run cleanup-browsers\n```\n\nThis utility will:\n1. Scan for Chrome processes that might be related to WhatsApp Web\n2. Display a list of potentially orphaned processes\n3. Ask for confirmation before terminating them\n4. Clean up the PID tracking file\n\n## Development\n\n### Project Structure\n\n- `src/index.ts`- Entry point\n- `src/server.ts`- MCP server implementation\n- `src/services/whatsapp.ts`- WhatsApp Web service\n- `src/tools/`- Tool implementations for various WhatsApp features\n- `src/types/`- TypeScript type definitions\n- `src/utils/`- Utility functions\n\n### Scripts\n\n- `npm run build`- Build the TypeScript code\n- `npm run dev`- Run in development mode with watch\n- `npm run lint`- Run ESLint\n- `npm run format`- Format code with Prettier\n- `npm run cleanup-browsers`- Detect and clean up orphaned Chrome browser processes\n- `npm test` - Run the unit test suite (fast, no browser needed)\n- `npm run test:watch` - Run unit tests in watch mode during development\n- `npm run test:e2e` - Build, then run end-to-end tests (spawns the real server incl. a headless browser)\n\n## Troubleshooting\n\n### Authentication Issues\n\n- If the QR code doesn't appear, try restarting the server\n- If you're already authenticated, no QR code will be shown (use `check_auth_status` to verify)\n- If you need to re-authenticate, use the `logout` tool first, then request a new QR code\n- WhatsApp limits the number of linked devices; you may need to remove an existing device\n- If you receive a message saying \"No QR code is currently available,\" but you're already authenticated, this is normal behavior - use `check_auth_status` to confirm your authentication status\n\n### Connection Issues\n\n- Make sure you have a stable internet connection\n- If the connection fails, try restarting the server\n- Check the logs for detailed error messages\n\n### Browser Process Issues\n\n- If you notice high CPU usage or memory consumption, there might be orphaned Chrome processes\n- Run `npm run cleanup-browsers` to detect and clean up orphaned processes\n- If the server crashes frequently, check for orphaned processes and clean them up\n- On Windows, you can also use Task Manager to look for multiple Chrome processes with \"headless\" in the command line\n- On Linux/macOS, use `ps aux | grep chrome` to check for orphaned processes\n\n## License\n\nMIT\n\n---\n\nThis project is a TypeScript port of the original [whatsapp-mcp](https://github.com/lharries/whatsapp-mcp) by [lharries](https://github.com/lharries).\n",
  "bytes": 11794,
  "sha": "b00a0e659c0d97fd810a546a1c97a388f837c51f4b5b6b691c92ac0835ef2c61",
  "repo_slug": "mario-andreschak/mcp-whatsapp-web",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mario_andreschak_mcp_whatsapp__d565df12/readme"
}