WhatsApp CLI

A powerful Node.js CLI tool and MCP Server for analyzing and extracting local WhatsApp data on macOS.

Configuration

This tool works with the local data stored by the WhatsApp for macOS Desktop app.

Prerequisites

• Node.js (v18 or higher)
• Full Disk Access: You must grant Full Disk Access to your terminal (Terminal.app, iTerm2, etc.) in System Settings > Privacy & Security > Full Disk Access.

Usage

🎮 Interactive Mode (Recommended)

Start a rich TUI experience to navigate through your chats, contacts, and calls:

npx whatsapp-cli explore

🤖 MCP Server (for AI Tools)

Integrate your WhatsApp data directly with AI models like Claude.

Configuration for Claude Desktop: Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/whatsapp-cli/dist/index.js", "mcp"]
    }
  }
}

⌨️ CLI Commands

• explore: Start the interactive TUI.
• check: Verify database local paths and permissions.
• chats: List recent chat sessions.
• messages <jid>: Show messages from a specific contact/group.
• contacts: List contacts from address book.
• calls: Recent call history.
• info: General overview and statistics.

Development

1. Install dependencies:

   npm install

2. Run in development:

   npm run dev -- explore

3. Run MCP Server (Dev):

   npm run mcp

4. Build:

   npm run build

Technical Reference

See docs/WHATSAPP.md for detailed database schema and storage architecture details.