Mcp Whatsapp

📱 MCP WhatsApp

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

[](https://python.org) [](https://modelcontextprotocol.io) [](LICENSE) [](https://github.com/gabriellopesdesouza2002/mcp-whatsapp)

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.

---

🚀 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+)

| Category | Tools | |----------|-------| | ⚙️ Setup | whatsapp_configure | | 🔗 Session | whatsapp_connect, whatsapp_disconnect, whatsapp_status, whatsapp_get_qrcode, whatsapp_health | | 💬 Messages | whatsapp_send_text, whatsapp_send_image, whatsapp_send_document, whatsapp_send_audio, whatsapp_send_video, whatsapp_send_sticker, whatsapp_send_location, whatsapp_send_contact, whatsapp_send_link, whatsapp_send_buttons, whatsapp_send_list, whatsapp_send_poll | | 📥 Chat | whatsapp_get_chats, whatsapp_get_unread_messages, whatsapp_get_messages, whatsapp_reply_message, whatsapp_delete_message, whatsapp_react, whatsapp_mark_read, whatsapp_download_media, whatsapp_search_messages, whatsapp_forward_message | | 👤 Users | whatsapp_get_user_info, whatsapp_get_contacts, whatsapp_search_contacts, whatsapp_check_phones, whatsapp_get_avatar | | 👥 Groups | whatsapp_list_groups, whatsapp_get_group_info, whatsapp_create_group, whatsapp_update_group_participants, whatsapp_get_group_invite_link | | 🔔 Webhook | whatsapp_set_webhook | | 📢 Newsletter | whatsapp_get_newsletter_messages, whatsapp_subscribe_newsletter | | 🔐 Admin | whatsapp_admin_list_users, whatsapp_admin_create_user, whatsapp_admin_delete_user |

---

💡 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:

| Format | Valid? | |--------|--------| | 5511999998888 | ✅ Brazil (DDD 11) | | 14155552671 | ✅ USA (415) | | +5511999998888 | ❌ Remove the + | | 011999998888 | ❌ Use country code |

---

📁 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](LICENSE).

---

Built with ❤️ for the MCP ecosystem

If this project helped you, please ⭐ star it!

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gabriellopesdesouza2002
• Source: gabriellopesdesouza2002/mcp-whatsapp
• License: MIT

Install and usage instructions live in the source repository linked above.