wp-mcp

# wp-mcp MCP server giving Claude Code read-only access to a paired WhatsApp account. Runs as a Docker container. Pair once via QR code (terminal or `/pair` web page), then query chats, messages, and media (images, transcribed audio, video frames) from any MCP-capable client. ## Quick start ```bash git clone git@github.com:alysnnix/wp-mcp.git cd wp-mcp cp .env.example .env # Generate a secure token node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" | xargs -I{} sed -i 's/changeme-use-openssl-rand-hex-32/{}/' .env docker compose build # ~5min first time (whisper.cpp + model download) docker compose up -d ``` Then pair: - Open `http://localhost:8765/pair` in a browser and scan the QR, OR - Run `docker logs -f wp-mcp` and scan the ASCII QR with WhatsApp > Settings > Linked Devices Verify: ```bash curl http://localhost:8765/healthz # {"wa":"connected"} ``` ## Connect as MCP server ### Claude Code Add to `~/.claude/mcp.json`: ```json { "mcpServers": { "whatsapp": { "url": "http://localhost:8765/mcp", "transport": "http", "headers": { "Authorization": "Bearer YOUR_TOKEN_HERE" } } } } ``` Replace `YOUR_TOKEN_HERE` with the value of `WP_MCP_TOKEN` from your `.env` file. ### Other MCP clients Any client that supports HTTP transport can connect: - **URL**: `http://localhost:8765/mcp` - **Transport**: HTTP (Streamable HTTP) - **Auth**: Bearer token in `Authorization` header - **Protocol**: JSON-RPC 2.0 (`tools/list`, `tools/call`) ## Tools | Tool | Purpose | | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `list_chats` | Recent chats, optional substring filter | | `get_messages` | Newest messages of a chat, with cursor pagination | | `download_media` | Image/audio/video/document. Audio is transcribed locally with Whisper. Video returns key frames + audio transcription. | | `search_messages` | FTS5 full-text search across all stored messages | | `get_chat_info` | Chat metadata by jid | | `get_contact_info` | Contact lookup by jid or phone | | `list_groups` | Group chats only | | `get_unread` | Latest unread message per chat | ## Configuration See `.env.example`. All vars are read at boot. | Var | Default | Purpose | | -------------------------- | ----------- | ----------------------------------------- | | `WP_MCP_TOKEN` | (required) | Bearer token for `/mcp` | | `WP_MCP_PORT` | `8765` | Listen port | | `WP_DATA_DIR` | `/data` | Persistent root (auth + DB + media cache) | | `WP_MCP_WRITE` | `false` | Reserved for future write tools | | `WP_WHISPER_MODEL` | `small` | `small` or `base` | | `WP_LOG_LEVEL` | `info` | `debug` `info` `warn` `error` | | `WP_LOG_MESSAGE_CONTENT` | `false` | Include message text in debug logs | | `WP_MEDIA_CACHE_MAX_BYTES` | `524288000` | LRU eviction trigger (500MB) | ## How it works 1. **Baileys** (WhatsApp Web protocol) connects as a linked device and receives messages in real-time 2. Messages are normalized and stored in **SQLite** with **FTS5** for full-text search 3. Media (audio/video) is processed on-demand with **ffmpeg** + **whisper.cpp** for transcription 4. An **HTTP server** (Hono) exposes 8 read-only MCP tools with bearer auth 5. History sync loads existing chats/messages on first pairing ## Development ```bash pnpm install # Local dev (needs .env with WP_DATA_DIR pointing to a local dir) pnpm dev # Run tests pnpm test # Full verification (typecheck + lint + test) pnpm verify ``` ## Risks WhatsApp's Terms of Service forbid unofficial clients. Use a secondary phone number — using your primary number risks a permanent ban. The MVP is read-only to keep traffic patterns low. ## License MIT