wacli-mcp

An MCP server that connects AI assistants to WhatsApp via wacli. Search messages, list chats, manage contacts, and send texts — all from Claude, Cursor, Kiro, or any MCP-compatible client.

Prerequisites

Install wacli and authenticate:

brew install steipete/tap/wacli
wacli auth

Scan the QR code with your WhatsApp mobile app to link the device.

Quick Start

Claude Code

claude mcp add wacli -- uvx --from "git+https://github.com/dgallitelli/wacli-mcp" wacli-mcp

Claude Desktop / Cursor / Windsurf

Add to your MCP config file:

{
  "mcpServers": {
    "wacli": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dgallitelli/wacli-mcp", "wacli-mcp"]
    }
  }
}

Kiro

Add to ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "wacli": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dgallitelli/wacli-mcp", "wacli-mcp"],
      "disabled": false
    }
  }
}

Tools

| Tool | Description | |------|-------------| | auth_status | Check WhatsApp authentication status | | doctor | Run diagnostics on store, auth, and search index | | list_chats | List chats with optional search query | | show_chat | Show details for a single chat by JID | | list_messages | List messages with date and chat filters | | search_messages | Full-text search (FTS5) with chat/sender/date/media filters | | show_message | Show a single message by ID | | message_context | Show surrounding messages for context | | search_contacts | Search contacts by name or phone number | | show_contact | Show contact details by JID | | refresh_contacts | Refresh contacts from WhatsApp into local DB | | list_groups | List known groups with optional search | | group_info | Fetch live group info | | send_text | Send a text message | | send_file | Send a file (image/video/audio/document) | | download_media | Download media from a message | | sync_once | Sync new messages then exit | | history_backfill | Request older messages from primary device | | resolve_recipient | Fuzzy-match a person/group name to a JID (searches contacts and groups) |

Resources

MCP clients that support resource browsing can navigate WhatsApp data directly:

| URI | Description | |-----|-------------| | whatsapp://chats | All chats | | whatsapp://contacts | All synced contacts | | whatsapp://groups | All known groups | | whatsapp://chats/{jid} | Chat details + recent messages | | whatsapp://contacts/{jid} | Contact details |

Prompts

Pre-built workflows that MCP clients can surface as suggested actions:

| Prompt | Description | |--------|-------------| | daily_digest | Summarize all today's messages, grouped by chat | | catch_up | Catch up on a specific chat since a given time | | draft_reply | Draft a contextual reply for a chat | | find_decision | Find when/where something was decided | | unanswered_messages | Find messages that expect a reply from you | | shared_media_recap | Recap photos, docs, and links shared in a chat |

Configuration

| Environment Variable | Description | Default | |---------------------|-------------|---------| | WACLI_PATH | Path to the wacli binary | Auto-detected via PATH |

Note: wacli itself reads WACLI_STORE_DIR from the environment to locate its store directory (default ~/.wacli). Since child processes inherit environment variables, you can set it in your MCP client's env block and wacli will pick it up directly.

Important Notes

• Authentication required: Run wacli auth before using this server. The MCP server cannot display QR codes.
• Store lock: Only one wacli process can access the store at a time. If you're running wacli sync in the background, send operations will fail with a lock error. Stop the sync process first.
• Send confirmation: The server instructs AI assistants to always confirm with the user before sending messages. However, this is advisory — configure your client's approval settings accordingly.
• Local DB: Read operations (search, list, show) query a local SQLite database. Run sync_once to pull the latest messages.

Development

git clone https://github.com/dgallitelli/wacli-mcp.git
cd wacli-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Run the linter:

ruff check src/
ruff format --check src/

Run the server directly:

wacli-mcp

Acknowledgments

This project is a thin MCP wrapper around wacli by Peter Steinberger. All WhatsApp connectivity, message syncing, and local storage are handled by wacli — this server simply exposes its CLI interface as MCP tools.

License

MIT