mcp server

wacli-mcp

MCP server for WhatsApp via wacli — search messages, list chats, send texts from any AI assistant

dgallitelli/wacli-mcpcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "wacli-mcp": {
      "command": "uvx",
      "args": [
        "wacli-mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 22, 2026

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