💬 pywa MCP Server

Unofficial Model Context Protocol (MCP) server that exposes the pywa WhatsApp Cloud API client as MCP tools.

⚠️ Disclaimer: Unofficial, third-party integration. Not affiliated with, endorsed by, or sponsored by WhatsApp, Meta, or the pywa project.

✨ Features

• 🔗 Full pywa surface — ~100 tools auto-discovered from the pywa WhatsApp client
• 🛡️ Type coercion — auto-parses JSON strings, hydrates dataclasses, coerces enums
• 📦 Smart serialization — bytes → base64, datetime → ISO, Path → string, enum → value, dataclass → dict
• 🎛️ Allowlist control — restrict exposed tools via PYWA_MCP_TOOLS env
• ⚙️ Var-args support — pywa methods with *args exposed via an _args field
• 🧪 Unit-tested — 37 tests covering serialization, coercion, schema, discovery
• 📖 MCP compliant — works with Claude Code, Claude Desktop, Cursor, Cline, etc.

🚀 Quick Start

Prerequisites

• Python 3.13+
• uv
• A Meta-approved WhatsApp Business phone number + access token
• An MCP-compatible client

1. Get pywa credentials

From the Meta Business dashboard:

• Phone Number ID — Meta → WhatsApp → API Setup
• Access token — system-user token (permanent) or temporary
• WABA ID — required for templates / flows / QR codes
• App ID / App secret — required for update validation + callback registration

2. Register with Claude Code

Option A — claude mcp add (recommended, zero-install)

Runs the server directly from git via uvx — no clone required.

Basic syntax:

claude mcp add [options] <name> -- <command> [args...]

Real example:

claude mcp add --transport stdio --scope user \
  --env WHATSAPP_PHONE_ID=<phone-id> \
  --env WHATSAPP_TOKEN=<token> \
  --env WHATSAPP_WABA_ID=<waba-id> \
  --env WHATSAPP_APP_ID=<app-id> \
  --env WHATSAPP_APP_SECRET=<app-secret> \
  pywa \
  -- uvx --from git+https://github.com/ianaleck/pywa-mcp-server pywa-mcp-server

Scope (--scope / -s):

• local (default) — private to this project
• user — across all your projects
• project — committed via .mcp.json

Verify / inspect / remove:

claude mcp list
claude mcp get pywa
claude mcp remove pywa

Option B — .mcp.json in the project

cp .mcp.json.example .mcp.json
# edit credentials; .mcp.json is gitignored

Option C — Claude Desktop / Cursor / Cline / other clients

Any MCP client that supports stdio works. Add:

{
  "mcpServers": {
    "pywa": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ianaleck/pywa-mcp-server", "pywa-mcp-server"],
      "env": {
        "WHATSAPP_PHONE_ID": "...",
        "WHATSAPP_TOKEN": "...",
        "WHATSAPP_WABA_ID": "...",
        "WHATSAPP_APP_ID": "...",
        "WHATSAPP_APP_SECRET": "..."
      }
    }
  }
}

Local development install

If you're modifying the server, clone and run from source:

git clone https://github.com/ianaleck/pywa-mcp-server.git
cd pywa-mcp-server
uv sync
# then point claude mcp add at:
#   uv --directory /absolute/path/to/pywa-mcp-server run pywa-mcp-server

🎯 What You Can Do

Once connected, you can ask Claude to:

💬 Messaging

• "Send a WhatsApp text to +27..., 'Order confirmed'"
• "Send the totp template to +27... with code 483921"
• "React to message wamid.xxx with 🎉"

📋 Templates

• "List all my approved templates"
• "Create a UTILITY template called 'order_shipped' with one body variable"
• "Show me the totp template details"

🌊 Flows

• "List all published flows"
• "Show metrics for the customer_pick flow over the last 30 days"
• "Fetch the JSON for flow 903243286082414"

🖼️ Media

• "Upload this image URL and send it to +27..."
• "Download media wamid.xxx to /tmp"

🔗 QR Codes

• "Create a QR code with the message 'Hi Orana!'"
• "Update QR code XYZ123 with a new prefilled message"

🏥 Health & Diagnostics

• "Check my WABA health status"
• "What's blocking my business-initiated sends?"

🛠️ Tool Catalog

Auto-discovered from pywa.WhatsApp. Full pywa docs at pywa.readthedocs.io.

⚙️ Environment Variables

🎛️ Tool Filtering

Default: every public pywa method except listen (which blocks indefinitely).

Allowlist: set PYWA_MCP_TOOLS=send_text,get_templates,send_template to expose only those.

⚠️ Caveats

• No inbound webhook. This server only sends/admin. listen, on_*, webhook_* register handlers / wait for inbound updates, but no FastAPI/Flask is run. For inbound support, run pywa's webhook in a separate process.
• stream_media returns a Python generator — unusable via MCP JSON transport. Use get_media_bytes (base64) or download_media (writes to disk, returns path).
• 24-hour window. Free-form sends to a user require they messaged you in the last 24h. Otherwise use an approved template.
• WABA health. Check get_business_account / get_business_phone_number — payment, calling SIP, and other issues cause silent send failures (can_send_message=BLOCKED).
• Schema drops type info for unions. MCP transport may stringify complex args; this server compensates by JSON-parsing strings when target type expects list/dict/dataclass.

🔄 Response Serialization

🧪 Development

git clone https://github.com/ianaleck/pywa-mcp-server.git
cd pywa-mcp-server
uv sync

# Run tests
uv run pytest tests/

# With coverage
uv run pytest tests/ --cov=main --cov-report=term-missing

37 unit tests, ~70% coverage. Remainder is async server boot (not unit-testable).

📋 API Requirements

This server requires a WhatsApp Cloud API account. You must comply with:

• WhatsApp Business Platform Terms
• WhatsApp Cloud API rate limits
• Meta Platform Terms

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Ensure all tests pass (uv run pytest tests/)
5. Commit your changes
6. Open a Pull Request

📄 License

MIT — see LICENSE.

🙏 Acknowledgments

• pywa by David Lev — the underlying WhatsApp Cloud API client
• Model Context Protocol — protocol spec
• Anthropic — Claude and the MCP SDK
• Meta — WhatsApp Cloud API

📞 Support

• 🐛 Bug Reports
• 💡 Feature Requests
• 📖 MCP Documentation
• 📖 pywa Documentation