内容
# 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)
