WhatsApp MCP 🟢

A self-hosted WhatsApp integration using the Model Context Protocol (MCP), enabling AI assistants (like Claude) to read and send WhatsApp messages directly from your desktop.

Built with:

• Bridge — Next.js + Baileys (WhatsApp Web API)
• Server — Python + FastMCP (MCP server)
• Storage — SQLite via better-sqlite3 (local data/ folder)

---

📁 Project Structure

whatsapp-mcp/
├── bridge/          # Next.js app — WhatsApp connection & REST API
│   ├── src/
│   │   ├── lib/
│   │   │   ├── whatsapp.ts      # Baileys socket, sync, message handling
│   │   │   └── database.ts      # SQLite schema & helpers
│   │   └── app/api/             # REST endpoints
│   ├── data/                    # Auto-created: auth + SQLite DB
│   └── package.json
│
└── server/          # Python MCP server — exposes tools to Claude
    ├── main.py      # FastMCP tools (send, receive, chats, contacts...)
    ├── pyproject.toml
    └── .env

---

✨ Features

• 🔐 QR Code Login — Scan once, sessions persist automatically
• 💬 Send & Receive messages via AI assistant
• 📋 Chats & Contacts — Browse all conversations and contacts
• 🔍 Search messages across all chats
• 🔄 Full History Sync — Syncs message history on first connect
• 🗄️ Local SQLite Storage — All data stays on your machine
• 🤖 MCP Compatible — Works with Claude Desktop and other MCP clients

---

🚀 Getting Started

Prerequisites

Tool	Version	Install
Node.js	≥ 18	nodejs.org
npm	≥ 9	Comes with Node.js
Python	≥ 3.11	python.org
uv	latest	pip install uv or docs.astral.sh/uv

---

Step 1 — Clone the Repository

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

---

Step 2 — Set Up the Bridge (Next.js)

The bridge connects to WhatsApp using the Baileys library and exposes a local REST API.

cd bridge
npm install
npm run dev

The bridge will start on http://localhost:3000.

On first run, it will create a data/ folder containing:

• data/auth/ — WhatsApp session credentials
• data/whatsapp.db — SQLite database with all messages, chats, and contacts

Note: The data/ folder is gitignored. Never commit it — it contains your session keys.

---

Step 3 — Connect WhatsApp (Scan QR Code)

1. Open http://localhost:3000 in your browser
2. Click Connect
3. Scan the QR code with your WhatsApp mobile app:
   • Open WhatsApp → Settings → Linked Devices → Link a Device
4. Wait for the sync to complete (first sync may take a minute depending on your chat history)

Once connected, the status will show Connected and message history will begin syncing to the local database.

---

Step 4 — Set Up the MCP Server (Python)

The server exposes WhatsApp functionality as MCP tools that Claude (or any MCP client) can call.

cd ../server

Create a .env file:

WHATSAPP_BRIDGE_URL=http://localhost:3000

Install dependencies and run using uv:

uv sync
uv run main.py

The MCP server will start on http://localhost:8001.

---

Step 5 — Connect to Claude Desktop

Add the following to your Claude Desktop MCP config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "whatsapp": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/whatsapp-mcp/server",
        "main.py"
      ],
      "env": {
        "WHATSAPP_BRIDGE_URL": "http://localhost:3000"
      }
    }
  }
}

Replace /absolute/path/to/whatsapp-mcp/server with the actual path on your machine.

Restart Claude Desktop. You should now see WhatsApp tools available in Claude.

---

🛠️ Available MCP Tools

Tool	Description
get_whatsapp_status	Check connection status
connect_whatsapp	Initialize WhatsApp connection
get_whatsapp_chats	List all chat conversations
get_whatsapp_contacts	List contacts with search support
get_whatsapp_messages	Get messages from a chat or search all
get_chat_history	Get message history for a specific chat
search_whatsapp_messages	Full-text search across all messages
send_whatsapp_message	Send a message by phone number
send_whatsapp_message_to_jid	Send a message by WhatsApp JID
logout_whatsapp	Log out and clear session

---

🌐 Bridge REST API Endpoints

The bridge exposes the following endpoints (used internally by the MCP server):

Method	Endpoint	Description
GET	/api/status	Connection status
POST	/api/status	Initialize connection
GET	/api/chats	List chats
GET	/api/contacts	List contacts
GET	/api/messages	Get/search messages
POST	/api/send	Send a message
POST	/api/logout	Logout

---

⚙️ Configuration

Bridge (bridge/.env.local)

# Optional: Set to 'development' to enable verbose Baileys logs
NODE_ENV=production

Server (server/.env)

WHATSAPP_BRIDGE_URL=http://localhost:3000

---

🗄️ Database

All data is stored locally in bridge/data/whatsapp.db (SQLite). The schema is auto-created by database.ts on first run and includes:

• messages — Full message history with content, type, sender, timestamp
• chats — All conversations with unread count and last message time
• contacts — Contact JIDs, names, and phone numbers
• sync_status — Tracks the last successful history sync

---

🔒 Privacy & Security

• All data is stored locally on your machine — nothing is sent to any external server
• WhatsApp session credentials are stored in bridge/data/auth/ — keep this folder secure
• The bridge and MCP server only communicate over localhost
• To fully remove your session, run logout or delete the bridge/data/ folder

---

🐛 Troubleshooting

QR code not appearing

• Make sure the bridge is running on port 3000
• Try refreshing the browser and clicking Connect again

Session expired / logged out

• Rescan the QR code — the old data/auth/ folder is cleared automatically on logout

Messages not syncing

• Wait for the initial sync to complete (check the status indicator)
• Large accounts may take 2–5 minutes on first connect

Claude can't see WhatsApp tools

• Verify the absolute path in claude_desktop_config.json
• Make sure uv is installed and accessible in your PATH
• Restart Claude Desktop after config changes

Port conflict

• Bridge default: 3000 — change with PORT=3001 npm run dev
• Server default: 8001 — change the port in main.py and update your .env

---

🤝 Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -m 'Add your feature')
4. Push to the branch (git push origin feature/your-feature)
5. Open a Pull Request

---

🙏 Acknowledgements

• Baileys — WhatsApp Web API library
• FastMCP — Python MCP framework
• Model Context Protocol — by Anthropic

---

⚠️ Disclaimer: This project uses an unofficial WhatsApp API (Baileys). Use responsibly and in accordance with WhatsApp's Terms of Service. The authors are not responsible for any account bans or misuse.