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

Resources

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

Prompts

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

Configuration

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