WhatsApp MCP

Human-in-the-Loop for AI Agents via WhatsApp

This is an MCP (Model Context Protocol) server that enables AI agents (like Claude or Cursor) to interact directly with you via WhatsApp. It bridges the gap between your autonomous AI and your phone, allowing for runtime confirmations, permission requests, or simple status updates while you are away from your computer.

• AI agent messaging
• AI agent confirmations
• Agent interrupt system
• AI alerts
• MCP server
• Cursor MCP
• Claude Desktop MCP
• AI notifications

Perfect for

• Cursor
• Claude Desktop
• Claude Code
• OpenCode
• Codex
• Autonomous AI workflows

Example

AI: Deploy to production?

WhatsApp: [YES] [NO]

You: YES

Agent continues.

🚀 Quick Start (NPX)

Since this package is published to NPM, you can run it directly via npx in your MCP configuration.

Cursor / Claude Configuration

Add this to your MCP configuration file:

{
  "mcpServers": {
    "whatsapp-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@mhrj/whatsapp-mcp"
      ],
      "env": {
        "WHATSAPP_TARGET_NUMBER": "1234567890@s.whatsapp.net"
      }
    }
  }
}

Note about Allowed Numbers: WHATSAPP_TARGET_NUMBER is the default recipient for all messages. However, if your target is a Whatsapp Group, any member of the group would be able to answer the AI by default. To restrict replies only to specific numbers (to prevent unauthorized people from answering), you can optionally add a comma-separated list of numbers as an environment variable: "WHATSAPP_ALLOWED_NUMBERS": "123@s.whatsapp.net,456@s.whatsapp.net". If set, the AI will ONLY honor responses from these specific matching users.

Troubleshooting npx: executable file not found in $PATH or env: node: No such file or directory: If your IDE/Agent complains it cannot find npx or node, it's because GUI apps (like Cursor) don't inherit your terminal's $PATH. To fix this, explicitly pass your PATH in the MCP env config.

      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
        "WHATSAPP_TARGET_NUMBER": "1234567890@s.whatsapp.net"
      }

Authentication (First time only)

The very first time you use the MCP server, it needs to authenticate with WhatsApp Web:

1. Call the connect tool via your Agent, or just use any WhatsApp tool normally. If the session is not authenticated yet, the server will trigger authentication automatically.
2. The tool result will return the QR code image directly in MCP content so modern clients can render it inline.
3. If your client does not render inline images, the server also tries to write a local fallback HTML page under ~/.whatsapp-mcp/qr.html.
4. Open WhatsApp on your phone -> Linked Devices -> Link a Device, and scan the QR.
5. The authentication session is saved to your home directory (~/.whatsapp-mcp/baileys_auth_info), so you don't need to scan it again across restarts.

Remote "Auto-Pilot" Workflow (Skip IDE Prompts)

To make your AI agent run fully autonomously and only ask for permissions/guidance via WhatsApp (allowing you to step away from your computer):

1. Remove IDE Security Blockers: When your agent (like Cursor or Claude) asks for permission to run a command or read a file, select Always Allow (or enable "yolo" mode in settings). This gives the agent the mechanical freedom to operate wit

... View full README on GitHub