wacli-mcp

# wacli-mcp An [MCP](https://modelcontextprotocol.io) server that connects AI assistants to WhatsApp via [wacli](https://github.com/steipete/wacli). Search messages, list chats, manage contacts, and send texts — all from Claude, Cursor, Kiro, or any MCP-compatible client. ## Prerequisites Install [wacli](https://github.com/steipete/wacli) and authenticate: ```bash brew install steipete/tap/wacli wacli auth ``` Scan the QR code with your WhatsApp mobile app to link the device. ## Quick Start ### Claude Code ```bash 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: ```json { "mcpServers": { "wacli": { "command": "uvx", "args": ["--from", "git+https://github.com/dgallitelli/wacli-mcp", "wacli-mcp"] } } } ``` ### Kiro Add to `~/.kiro/settings/mcp.json`: ```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 ```bash 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: ```bash ruff check src/ ruff format --check src/ ``` Run the server directly: ```bash wacli-mcp ``` ## Acknowledgments This project is a thin MCP wrapper around [wacli](https://github.com/steipete/wacli) by [Peter Steinberger](https://github.com/steipete). All WhatsApp connectivity, message syncing, and local storage are handled by wacli — this server simply exposes its CLI interface as MCP tools. ## License [MIT](LICENSE)