Overview

This MCP (Model Context Protocol) server provides a lightweight HTTP interface to manage a personal WhatsApp account programmatically. It exposes endpoints for reading and searching chat history, sending messages to individual contacts, and basic group management operations — enabling developers to integrate WhatsApp interactions into scripts, bots, or other automation tools without building a WhatsApp client from scratch.

The server is intended for personal or developer accounts (not bulk messaging) and works by bridging a connected WhatsApp session with the MCP-style API. It’s useful when you want quick programmatic access to your own chat context for tasks like finding recent messages, sending short updates, or creating and maintaining small groups.

Features

Search across chats and messages (keyword, contact, time-range)
Send text messages to contacts or group IDs
Retrieve chat and contact lists with metadata
Create groups and manage membership (add/remove)
Simple HTTP API compatible with MCP-style requests
Configurable authentication and session persistence
Docker-friendly and scriptable via curl or any HTTP client

Installation / Configuration

Prerequisites:

Git
Node.js (or Python/runtime as required by the repository) — check the project README for exact runtime
Docker (optional)

Clone the repo:

git clone https://github.com/lharries/whatsapp-mcp.git
cd whatsapp-mcp

Install dependencies (example for Node.js):

npm install

Create a .env file or copy the example env file and edit values:

cp .env.example .env
# Edit .env: set MCP_PORT, AUTH_TOKEN, SESSION_PATH, etc.

Common environment variables (example):

MCP_PORT=8080
AUTH_TOKEN=change_this_to_a_secure_token
SESSION_PATH=./session.json
WHATSAPP_CLIENT=web
LOG_LEVEL=info

Run locally:

npm start
# or, if the project uses node directly:
node server.js

Run with Docker (example docker-compose):

version: '3'
services:
  whatsapp-mcp:
    image: lharries/whatsapp-mcp:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - MCP_PORT=8080
      - AUTH_TOKEN=change_this
      - SESSION_PATH=/data/session.json
    volumes:
      - ./data:/data

docker-compose up -d

Authentication: The server typically expects a shared token or header (e.g., Authorization: Bearer <AUTH_TOKEN>) — configure this in the .env and supply it on requests.

Available Resources

Repository: https://github.com/lharries/whatsapp-mcp
API endpoints (examples listed below)
Session persistence file to avoid repeated re-authentication
Logs and debug output controllable via LOG_LEVEL

API Endpoints (common examples)

Method	Path	Purpose
GET	/chats	List chats and metadata
GET	/contacts	List contacts
GET	/search?q=term	Search messages across chats
POST	/messages/send	Send a text message
POST	/groups	Create a group
POST	/groups/:id/members	Add members to a group
DELETE	/groups/:id/members/:memberId	Remove member from group

Note: Use the GitHub README or API docs in the repo for exact paths and payload shapes.

Use Cases

Quick personal message from a script

Scenario: Send a short reminder to a partner when a CI build finishes.

Example:

curl -X POST "http://localhost:8080/messages/send" \
  -H "Authorization: Bearer change_this_to_a_secure_token" \
  -H "Content-Type: application/json" \
  -d '{"to":"+15551234567","text":"CI build finished: all tests passed."}'

Search recent messages across chats

Scenario: Find the last message mentioning “invoice” across all chats to forward to your accounting app.

Example:

curl -G "http://localhost:8080/search" \
  -H "Authorization: Bearer change_this_to_a_secure_token" \
  --data-urlencode "q=invoice" \
  --data-urlencode "limit=20"

Manage a small group programmatically

Scenario: Create a temporary event group and add attendees.

Example (create group):

curl -X POST "http://localhost:8080/groups" \
  -H "Authorization: Bearer change_this_to_a_secure_token" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Project Kickoff","participants":["+15551234567","+15559876543"]}'

Add a member:

curl -X POST "http://localhost:8080/groups/<groupId>/members" \
  -H "Authorization: Bearer change_this_to_a_secure_token" \
  -H "Content-Type: application/json" \
  -d '{"member":"+15557654321"}'

Build a search-backed assistant
- Scenario: Use message search to feed relevant chat snippets into a local assistant or indexer to provide context-aware replies.

Notes and Best Practices

This tool is designed for personal use and automation of your own WhatsApp account. Respect WhatsApp’s terms of service and anti-spam policies.
Secure your server with a strong AUTH_TOKEN and, if exposed to the internet, additional measures (reverse proxy TLS, IP restrictions).
Keep session files backed up and protected since they grant access to the account.
Consult the repository README and issues for runtime-specific instructions, supported platforms, and troubleshooting.

For the latest usage details, examples, and updates, see the project on GitHub: https://github.com/lharries/whatsapp-mcp

WhatsApp MCP Server: Personal Messaging & Group Management