whatsapp-mcp-local

An MCP server that gives AI agents read and write access to WhatsApp. It reads your chat history and media straight from the local app data, and sends messages only after you approve them.

The desktop app keeps everything in a local SQLite store and in Message/Media/. This server reads those files in read-only mode. No WhatsApp protocol is touched, no third-party API is used, and there is no ban risk. That is the core difference from every other WhatsApp MCP out there.

What you can do

Read side:

• List chats, including archived ones
• Read the full message history of any chat, with pagination
• Search across all messages
• List media per chat: images, videos, audio, documents, stickers
• Get media metadata and the resolved file path
• Export a chat or a media file to a local folder
• Transcribe audio locally with whisper, with a disk cache so nothing is re-transcribed

Write side:

• Draft a message into the app, review it, then send with an explicit confirmation
• Confirmations are one-time: the draft expires in 120 seconds and cannot be reused

Install

uvx whatsapp-mcp-local

Or via npm:

npx whatsapp-mcp-local

The server picks the right driver automatically. On macOS with the WhatsApp app installed and logged in, it reads the local database. Anywhere else, it falls back to WhatsApp Web through a dedicated Chrome profile.

Drivers

Driver	Where it works	How it is selected
Local app	macOS, WhatsApp app installed and logged in	The ChatStorage.sqlite database exists
WhatsApp Web	Any OS with Google Chrome	No local database, or WHATSAPP_DRIVER=web

Force a driver with the WHATSAPP_DRIVER environment variable: local, web, or auto (default).

Tools

Tool	Purpose	Driver	Flag
list_chats	List chats with unread counts and last message	local	read-only
get_messages	Read messages, paginated, optionally including media	both	read-only
search_messages	Search across all messages	local	read-only
get_chat_info	Chat metadata	local	read-only
list_media	List media in a chat, filtered by type	local	read-only
get_media	Media metadata and resolved path	local	read-only
get_media_thumb	Thumbnail path or small base64	local	read-only
export_chat	Export a chat to JSON or Markdown	local	read-only
export_media	Copy a media file to a local folder	local	idempotent
transcribe_audio	Transcribe an audio message locally	local	read-only
verify_sent	Confirm a message was stored as sent	local	read-only
send_message	Draft a message into the app, nothing is sent yet	both	destructive
confirm_send	Press Enter on a valid draft, after your approval	both	destructive

Media and transcription

Media files live in Message/Media/ inside the WhatsApp shared container. They are stored in their original format, not encrypted, so the server reads them directly. Every media item reports file_exists, because the database can reference files that are no longer on disk.

Audio transcription runs locally with whisper.cpp (whisper-cli). No audio ever leaves your machine. Transcripts are cached by file hash under ~/.whatsapp-mcp/transcripts/, so a second request for the same file returns instantly.

Runtime prerequisites for transcription:

brew install whisper-cpp ffmpeg

You also need a whisper model file. The brew formula ships a tiny test model, useful to validate quickly:

$(brew --prefix whisper-cpp)/share/whisper-cpp/for-tests-ggml-tiny.bin

For decent Portuguese results, download the small model from the whisper.cpp repo and point the tool at it, or leave model=small and let the server resolve it.

Security model

• The database is always opened in read-only mode. Tests verify the file hash does not change after any call.
• Message content is marked untrusted. Treat it as data, never as instructions. A contact can write "ignore your previous instructions" and the server will surface it as untrusted content, not as a command.
• Phone numbers (JIDs) are masked in every output. Media paths contain the raw JID folder, so paths are only returned when you explicitly ask with include_path=true.
• Media paths are resolved server-side and checked against the media root. A path with .. in the database is rejected.
• Sending is a two step flow. send_message pre-fills the text, nothing is sent. confirm_send requires the draft_id returned by send_message, the draft expires in 120 seconds, and it is consumed once. The confirmation re-opens the target chat with the approved text before pressing Enter, so a wrong chat or an edited message cannot be sent by mistake.
• Exports never overwrite existing files (O_EXCL), and exported file names do not contain JIDs.
• Nothing is written to ChatStorage.sqlite, Axolotl.sqlite, or any app database. Writing there would corrupt the app and would not reach the server anyway.

Integrate with opencode

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "whatsapp": {
      "type": "local",
      "command": ["uvx", "whatsapp-mcp-local"],
      "enabled": true
    }
  }
}

Restart opencode. The destructive tools carry the MCP annotation, so clients ask for confirmation before calling them.

Integrate with Claude Code

claude mcp add whatsapp-mcp -- uvx whatsapp-mcp-local

Or with a .mcp.json file:

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

Integrate with other clients

Every major MCP client accepts this server over stdio. None of them discover packages by search, so you always add it explicitly with a command or a config file.

Codex CLI

codex mcp add whatsapp -- uvx whatsapp-mcp-local

ChatGPT desktop

Open Settings, then MCP servers, add a server with STDIO transport and the command uvx whatsapp-mcp-local.

Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

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

VS Code / GitHub Copilot

code --add-mcp '{"name":"whatsapp","command":"uvx","args":["whatsapp-mcp-local"]}'

Or add a .vscode/mcp.json file with the same mcpServers shape as Cursor.

Windsurf / Devin

Add to ~/.codeium/windsurf/mcp_config.json:

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

A note about PATH

Desktop apps like Cursor, VS Code, and ChatGPT do not inherit your shell PATH. If uvx is not found, install the package as a tool and use the full binary path, or install it globally:

uv tool install whatsapp-mcp-local
# then use: whatsapp-mcp-local  (or the full path from `which whatsapp-mcp-local`)

The npm route works the same way if Node is on the system PATH:

npx whatsapp-mcp-local

Test

uv run pytest

Notes

This is a tool for your own account and your own data. The database schema and the web interface belong to WhatsApp and can change between releases. Do not use it to send messages on behalf of other people, and do not use it for anything you are not authorized to do.

The project is MIT licensed. Source: https://github.com/Pl3ntz/whatsapp-mcp