📱 MCP WhatsApp

Send messages, images, documents and more on WhatsApp — directly from any AI.

Works with Claude, Gemini, Cursor, Windsurf, Continue.dev and any MCP-compatible AI.

100% Open Source and MIT Licensed.

✨ What can you do?

Just talk to your AI naturally:

"Send a message to +5511999998888 saying the meeting is postponed"

"Send the invoice.pdf to the Clients group"

"Get the last 20 messages from my support chat"

"Create a group called 'Team Sprint' with these numbers"

No code. No manual API calls. Just ask.

Related MCP server: MCP WPPConnect Server

🚀 Quick Start (3 steps)

Step 1 — Clone and start WuzAPI

git clone https://github.com/YOUR_USER/mcp-whatsapp
cd mcp-whatsapp
docker compose up -d

That's it — WuzAPI starts automatically on http://localhost:7143 with message history enabled. ✅

The included docker-compose.yml sets everything up for you.
Default admin token: admin123 (change via WUZAPI_ADMIN_TOKEN env var).

Step 2 — Install the MCP server

python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

pip install -e .

Step 3 — Register with Claude Code (global, one-time)

# Windows (replace with your absolute path)
claude mcp add whatsapp -s user -- C:\path\to\mcp-whatsapp\.venv\Scripts\python.exe -m mcp_whatsapp.server

# Linux / macOS (replace with your absolute path)
claude mcp add whatsapp -s user -- /path/to/mcp-whatsapp/.venv/bin/python -m mcp_whatsapp.server

Restart Claude, then just ask:

"Configure my WhatsApp with token mytoken123"

Magic: The server will automatically create the user in WuzAPI for you (Plug & Play). No manual dashboard work required! 🪄

🔑 Manual Configuration (Optional)

If you prefer to use the dashboard, it is available at http://localhost:7143.

1. Open http://localhost:7143 → click Admin Mode

2. Enter the admin token — default is admin123

3. Go to Users → Create User, enter any name and choose a token.

"Configure my WhatsApp with token myusertoken"

💡 Two tokens, two purposes:

• User token → sends/receives messages — this is what you use daily

• Admin token → manages users — only needed for whatsapp_admin_* tools

🔌 Connect to Your AI

Claude Code (recommended)

claude mcp add whatsapp -s user -- \
  /path/to/.venv/bin/python -m mcp_whatsapp.server

Then ask Claude to configure:

"Configure my WhatsApp: token=abc123, url=http://localhost:7143"

Claude Desktop

Add to claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "whatsapp": {
      "command": "/path/to/mcp-whatsapp/.venv/bin/python",
      "args": ["-m", "mcp_whatsapp.server"],
      "env": {
        "WUZAPI_BASE_URL": "http://localhost:7143",
        "WUZAPI_TOKEN": "your_token_here"
      }
    }
  }
}

Cursor / Windsurf / Continue.dev

Add to your editor's MCP config file:

{
  "mcpServers": {
    "whatsapp": {
      "command": "/path/to/mcp-whatsapp/.venv/bin/python",
      "args": ["-m", "mcp_whatsapp.server"],
      "env": {
        "WUZAPI_BASE_URL": "http://localhost:7143",
        "WUZAPI_TOKEN": "your_token_here"
      }
    }
  }
}

Any other MCP-compatible AI

• Transport: stdio (standard)

• Command: python -m mcp_whatsapp.server

• Env vars: WUZAPI_BASE_URL, WUZAPI_TOKEN

🛠️ Available Tools (30+)

💡 Usage Examples

First-time setup

You: "Configure my WhatsApp with token abc123"
Claude: ✅ Configuration saved! Now use whatsapp_connect() to connect.

You: "Connect my WhatsApp"
Claude: [generates QR Code — scan with your phone]

You: "Check if WhatsApp is connected"
Claude: ✅ Connected as +5511999998888

Sending messages

You: "Send 'Hello!' to +5511999998888"
You: "Send the file report.pdf to the Sales group"
You: "Send my location to +5511987654321"
You: "React with 👍 to the last message in chat 5511999998888@s.whatsapp.net"

Managing groups

You: "List all my WhatsApp groups"
You: "Create a group 'Project X' with +5511111111111 and +5522222222222"
You: "Get the invite link for group 120363XXXXXXXX@g.us"

📞 Phone Number Format

WhatsApp via WuzAPI uses numbers without the + prefix:

📁 Project Structure

mcp-whatsapp/
├── pyproject.toml          # Python project config
├── .env.example            # Environment variables template
└── src/
    └── mcp_whatsapp/
        ├── server.py       # MCP server with all tools
        └── wuzapi_client.py # Async HTTP client for WuzAPI

🛡️ Security & Responsible Use

IMPORTANT: This project uses an unofficial WhatsApp API. Use it at your own risk.

To ensure your account stays safe and you remain compliant with global data laws (LGPD/GDPR), please follow these guidelines:

1. Avoid Spam: Do not use this tool for bulk messaging or automated marketing. Excessive automated activity is the #1 cause of WhatsApp account bans.

2. Privacy Guardrails: By default, this server includes masking for sensitive information (PII) like CPFs, Credit Cards, and Emails (when WUZAPI_PRIVACY_MODE=true).

3. Audit Logs: All tool calls are logged in logs/audit_privacy.log. This is essential for transparency and accountability.

4. Token Safety: Never share your WUZAPI_TOKEN or WUZAPI_ADMIN_TOKEN. These grant full access to your messages.

5. AI Autonomy: Be careful when giving the AI "autonomy" to send messages. Always review the output if the AI is performing high-stakes tasks.

6. Terms of Service: Be aware that using unofficial APIs violates WhatsApp's Terms of Service. This tool is intended for personal productivity and research.

🤝 Contributing

Contributions are welcome! Feel free to open issues and pull requests.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes

4. Open a Pull Request

📄 License

This project is open-source and available under the MIT License.

Built with ❤️ for the MCP ecosystem

If this project helped you, please ⭐ star it!