WhatsApp MCP Server

Bring your WhatsApp account into MCP-compatible AI clients with a local-first Go server. Search chats, inspect history, download media, and send messages without shipping your archive to a third-party backend by default.

Important: your WhatsApp archive stays under your control by default. This server is designed to work locally first, not by uploading your chat history to a third-party backend.

This is for people who want their AI assistant to work with real WhatsApp context:

before meetings, pull the important points from a noisy group chat
search a project conversation without opening WhatsApp Web
draft or send replies from an MCP client
keep access narrow with an allowlist instead of exposing your entire account

Privacy-First

By default, this project is built to keep your WhatsApp archive under your control.

chat history is stored locally
media is downloaded locally
auth/session data stays local
nothing is sent to a third-party backend unless you explicitly wire up your own outbound integration, such as webhooks

Why It Feels Different

local-first: auth, messages, logs, and media stay on your machine by default
scoped access: expose only the chats you explicitly allow
MCP-native: works with clients that can talk to MCP over HTTP
automation-ready: optional webhooks let you push events into your own systems

Example Prompts

Once connected, your MCP client can do things like:

Summarize the last 24 hours from my "Family Logistics" chat in 5 bullets.

Find the message where Ahmet shared the Wi-Fi password last month.

Show recent media from the "Site Visits" group and tell me what was sent.

Draft a reply to the last message in the "Product Launch" group and keep it concise.

List the chats with the most activity this week.

Good First Use Case

The best first demo is not "read all my WhatsApp." It is:

allowlist one chat you already use for coordination
pair WhatsApp once
ask your MCP client for a short summary, action items, or the last decision that was made

That keeps the setup safe, concrete, and immediately useful.

Video Walkthrough

A real-world use-case walkthrough video is planned. Until then, the easiest story to demo is:

start the server locally
pair via QR
allowlist one real group chat
ask your MCP client to summarize recent messages and draft a reply

A starter script for that walkthrough lives in docs/demo-use-case.md.

Quick Start

1. Run the Server

Use a release binary, Docker, or Go source. The fastest source-based path is:

git clone https://github.com/caglayan/whatsapp-mcp-server.git
cd whatsapp-mcp-server
go mod download
go run .

If you want to override the default storage location:

go run . --data-dir ./data

2. Configure

Create a .env file if you want stable local configuration:

cp .env.example .env

Available variables:

# MCP server
MCP_API_KEY=your-secret-api-key-here
MCP_PORT=8080
DATA_DIR=
MCP_ALLOWED_CHAT_JIDS=

# Logging
LOG_LEVEL=INFO

# Timezone
TIMEZONE=America/Sao_Paulo

# Media auto-download
MEDIA_AUTO_DOWNLOAD_ENABLED=true
MEDIA_AUTO_DOWNLOAD_FROM_HISTORY=false
MEDIA_AUTO_DOWNLOAD_MAX_SIZE_MB=10
MEDIA_AUTO_DOWNLOAD_TYPES=image,audio,sticker

# Webhooks
WEBHOOK_URL=
WEBHOOK_MAX_RETRIES=3
WEBHOOK_TIMEOUT_SECONDS=10
WEBHOOK_WORKER_POOL_SIZE=3

Notes:

DATA_DIR is optional. If empty, the server uses the default per-user storage directory for your OS.
MCP_ALLOWED_CHAT_JIDS is optional. If empty, MCP can access all chats. If set, only those chats are stored and exposed.
TIMEZONE defaults to UTC if not set.
WEBHOOK_URL is optional. Leave it empty to disable webhooks.

Example allowlist:

MCP_ALLOWED_CHAT_JIDS=5511999999999@s.whatsapp.net,120363025353151234@g.us

When MCP_ALLOWED_CHAT_JIDS is set, the server only stores and exposes those chats. That applies to ingestion, search, history sync, and sending through MCP.

3. Connect WhatsApp

The first run prints a QR code in the terminal and also saves it into the data directory. Scan it from WhatsApp:

Settings -> Linked Devices -> Link a Device

4. Connect Your MCP Client

Example Claude Desktop config:

{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:8080/mcp/your-secret-api-key",
      "transport": "http"
    }
  }
}

5. Verify It Is Up

Health check:

curl http://localhost:8080/health

If you get a healthy response and your WhatsApp device is paired, your MCP client can start querying chats immediately.

What Gets Stored Locally

The server is local-first. By default it stores:

WhatsApp auth/session database
message database in SQLite
downloaded media files
WhatsApp log file
QR image for first-time pairing

Nothing in this repo uploads your message database anywhere by default. If you enable webhooks, webhook deliveries are an explicit outbound integration.

Other Install Options

Docker

cp .env.example .env
docker compose up --build

Docker persists data in ./data on the host and uses /app/data inside the container.

Use a Release Binary

Tagged releases publish prebuilt binaries for macOS, Linux, and Windows in GitHub Releases. Download the asset that matches your OS and CPU, make it executable if needed, then run:

./whatsapp-mcp-server --data-dir ./data

Build from Source

go build -o whatsapp-mcp-server .
./whatsapp-mcp-server --data-dir ./data

What You Get

WhatsApp session handling and QR-based pairing
SQLite-backed local message storage
MCP HTTP endpoint for tools, prompts, and resources
media download support
webhook delivery for outbound integrations
optional per-chat allowlisting
migration CLI for storage changes

Configuration

Available configuration lives in .env.example.

Key options:

MCP_API_KEY: API key used in the MCP path segment
MCP_PORT: HTTP port, default 8080
DATA_DIR: override the default per-user storage directory
TIMEZONE: timezone used for timestamps returned by MCP tools
MCP_ALLOWED_CHAT_JIDS: comma-separated allowlist of chat or group JIDs
MEDIA_AUTO_DOWNLOAD_*: control automatic media download behavior
WEBHOOK_*: configure webhook delivery

Security Notes

This server is powerful. Run it only in a trusted environment.
Do not expose the HTTP endpoint directly to the public internet unless you put it behind a trusted network boundary.
Treat MCP_API_KEY as a secret.
Do not commit .env, SQLite databases, logs, or QR images.
If you only want MCP to access specific conversations, set MCP_ALLOWED_CHAT_JIDS.

Who This Is For

developers building private AI workflows on top of their own WhatsApp account
operators who want searchable message context without SaaS lock-in
tinkerers who prefer a local database and explicit control over what gets exposed

If you want a hosted team product with shared access controls and cloud administration, this repo is probably not the right shape. It is intentionally local-first.

Development

Run tests:

go test ./...

Useful local commands:

go run .
go run ./cmd/migrate status
go run ./cmd/migrate create add_new_feature

Roadmap Ideas

richer examples for Claude Desktop and other MCP clients
more polished demo assets and a public walkthrough video
additional operational guidance for self-hosted setups

Release Flow

Tagged releases drive the public distribution:

GitHub Actions builds platform binaries
binaries are uploaded to GitHub Releases with checksums.txt

GitHub repository links in this repo are configured for caglayan/whatsapp-mcp-server.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for local development and migration workflow. If you build a useful workflow on top of this server, opening an issue with the use case is useful product feedback.

License

GPL-3.0-only. See LICENSE.

MCP Servers