WhatsApp MCP Server — connect AI agents to WhatsApp as a regular user.
MCP (Model Context Protocol) server that connects AI agents to WhatsApp through the multi-device API. Works as a regular WhatsApp user — not a business bot.
Built with Baileys, Bun, and TypeScript.
⚠️ Disclaimer: This project uses an unofficial WhatsApp API. Your account could be restricted or banned by WhatsApp. Use a secondary phone number. We are not responsible for any account actions taken by WhatsApp.
- 🔌 MCP Protocol — works with Claude Desktop, Cursor, and any MCP client
- 💬 Messages — send, read, edit, delete, forward, react, polls, star
- 📎 Media — images, videos, documents, stickers, voice notes, audio, locations, contacts
- 👥 Groups — create, manage members, promote/demote admins, invite links, settings
- 🏘️ Communities — create, link/unlink groups, manage members
- 📢 Channels — create, follow/unfollow, mute newsletters
- 🏷️ Labels — label chats and messages (WhatsApp Business)
- 🔒 Privacy — last seen, profile photo, online status, read receipts, group add
- 👤 Profile — update name, status, picture, business profiles, call links
- 🗂️ Chats — list, search, archive, mute, pin, mark read, disappearing messages
- 🔐 Machine-bound sessions — encrypted with hardware ID, useless if copied to another device
- 📦 Single binary — no Node.js, no npm, just download and run
Grab the latest release for your platform from GitHub Releases.
# Linux
chmod +x mcp-whatsapp-linux-x64
./mcp-whatsapp-linux-x64
# macOS
chmod +x mcp-whatsapp-darwin-arm64
./mcp-whatsapp-darwin-arm64git clone https://github.com/gridmint/mcp-whatsapp.git
cd mcp-whatsapp
bun install
bun run build
./mcp-whatsappAdd to your Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"whatsapp": {
"command": "/path/to/mcp-whatsapp"
}
}
}| Tool | Description |
|---|---|
send_message |
Send text with optional quote/reply |
send_image |
Send an image with optional caption |
send_document |
Send a file/document |
send_reaction |
React to a message with emoji |
read_messages |
Read recent messages from a chat |
delete_message |
Delete a message for everyone |
edit_message |
Edit a sent message |
forward_message |
Forward a message to another chat |
create_poll |
Create a poll with multiple options |
star_message |
Star or unstar a message |
| Tool | Description |
|---|---|
list_chats |
List all conversations |
get_chat_info |
Get chat/group details |
search_messages |
Search messages by keyword |
archive_chat |
Archive or unarchive a chat |
mute_chat |
Mute or unmute notifications |
pin_chat |
Pin or unpin a chat |
mark_as_read |
Mark all messages as read |
| Tool | Description |
|---|---|
check_number |
Check if number is on WhatsApp |
get_profile_picture |
Get profile picture URL |
get_status |
Get contact's about/status text |
block_contact |
Block or unblock a contact |
set_presence |
Set online/offline/typing status |
| Tool | Description |
|---|---|
create_group |
Create a new group |
get_group_metadata |
Get full group info & participants |
update_group_subject |
Change group name |
update_group_description |
Change group description |
add_group_members |
Add members to a group |
remove_group_members |
Remove members from a group |
promote_group_admin |
Promote members to admin |
demote_group_admin |
Demote admins to members |
leave_group |
Leave a group |
get_group_invite_link |
Get group invite link |
revoke_group_invite |
Revoke and regenerate invite link |
join_group_via_invite |
Join group using invite code |
update_group_settings |
Update who can send/edit info |
| Tool | Description |
|---|---|
send_video |
Send video (or GIF) |
send_sticker |
Send a sticker |
send_voice |
Send voice note (with waveform) |
send_audio |
Send audio file |
send_location |
Send a location pin |
send_contact |
Send a contact card (vCard) |
download_media |
Download media from a message |
| Tool | Description |
|---|---|
create_newsletter |
Create a WhatsApp Channel |
get_newsletter_info |
Get channel metadata |
follow_newsletter |
Subscribe to a channel |
unfollow_newsletter |
Unsubscribe from a channel |
mute_newsletter |
Mute channel notifications |
unmute_newsletter |
Unmute channel notifications |
| Tool | Description |
|---|---|
get_privacy_settings |
Get current privacy settings |
update_last_seen_privacy |
Who sees your last seen |
update_profile_picture_privacy |
Who sees your profile photo |
update_status_privacy |
Who sees your about/status |
update_read_receipts_privacy |
Toggle blue ticks |
update_groups_add_privacy |
Who can add you to groups |
update_online_privacy |
Who sees when you're online |
| Tool | Description |
|---|---|
create_community |
Create a new community |
get_community_metadata |
Get community info |
community_fetch_groups |
List linked groups |
community_create_group |
Create a group in a community |
community_link_group |
Link existing group to community |
community_unlink_group |
Unlink a group |
community_update_subject |
Update community name |
community_update_description |
Update community description |
leave_community |
Leave a community |
community_add_members |
Add members |
community_remove_members |
Remove members |
| Tool | Description |
|---|---|
add_chat_label |
Add label to a chat |
remove_chat_label |
Remove label from a chat |
add_message_label |
Add label to a message |
remove_message_label |
Remove label from a message |
| Tool | Description |
|---|---|
update_profile_name |
Change your display name |
update_profile_status |
Change your about text |
update_profile_picture |
Change your profile photo |
get_business_profile |
Get business profile info |
create_call_link |
Create audio/video call link |
set_disappearing_messages |
Toggle disappearing messages |
| Tool | Description |
|---|---|
get_connection_status |
Connection state + rate limit stats |
Built-in sliding-window rate limiter protects your account from bans:
- Global: 30 write operations per minute
- Per-chat: 10 write operations per minute
- Read operations (list, search, get) are not rate-limited
- Exceeding limits returns a clear error with retry timing
On first run, a QR code is displayed in the terminal. Scan it with WhatsApp on your phone:
- Open WhatsApp → Settings → Linked Devices → Link a Device
- Scan the QR code
Session is saved to ~/.mcp-whatsapp/auth/ — you won't need to scan again unless you log out.
Session files are encrypted at rest (AES-256-GCM). By default, the encryption key is derived from your machine's hardware ID — no configuration needed.
- ✅ On your machine — works automatically, no extra steps
- ❌ Copied to another machine — can't decrypt, must scan QR again
- ❌ Stolen backup — encrypted, useless without the original hardware
Optionally, set your own encryption key via environment variable:
export MCP_WHATSAPP_SESSION_KEY=my-secret-keyThis is useful for Docker containers, CI, or when you want to control the key yourself. If set, it takes priority over the machine ID.
Additional recommendations:
- Use a secondary phone number — your main account stays safe
- Check Linked Devices in WhatsApp periodically
- Keep your machine secure (disk encryption, strong passwords)
bun install # install dependencies
bun run dev # run in development mode
bun run lint # check code with Biome
bun run lint:fix # auto-fix lint issues
bun run format # format code
bun test # run tests-
Group management(v0.2.0) -
Stickers, GIFs, voice messages(v0.2.0) -
Newsletters/Channels(v0.2.0) -
Privacy settings(v0.2.0) -
Polls(v0.2.0) -
Community management(v0.3.0) -
Business features (labels)(v0.3.0) -
Profile management(v0.3.0) -
Call link creation(v0.3.0) -
Disappearing messages(v0.3.0) - Status/Stories (view and post)
- Product catalogs
- Rate limiting (ban protection)
MIT — see LICENSE.
- mcp-telegram — Telegram MCP server by the same team