mcp reference
WhatsApp-Use MCP.
One MCP server. Add it to Claude Desktop, Cursor, Cline, or any MCP-aware client. Pair a WhatsApp account, then read, write, send, search, and receive notifications — all as tools your agent can call.
introduction
Introduction
WhatsApp-Use exposes a single MCP server. Your agent connects with an API key, pairs one or more WhatsApp accounts, and then has every tool below available — sending and reading messages, managing chats and groups, searching history, and receiving live notifications.
quickstart
Quickstart
Pick your MCP client, drop the snippet into the config file, restart the client. The configuration is identical across clients — only the file location changes.
{
"mcpServers": {
"whatsapp": {
"command": "npx",
"args": ["-y", "@whatsapp-use/mcp"],
"env": {
"WUSE_API_KEY": "wuse_live_..."
}
}
}
}{
"mcpServers": {
"whatsapp": {
"command": "npx",
"args": ["-y", "@whatsapp-use/mcp"],
"env": {
"WUSE_API_KEY": "wuse_live_..."
}
}
}
}{
"mcpServers": {
"whatsapp": {
"command": "npx",
"args": ["-y", "@whatsapp-use/mcp"],
"env": {
"WUSE_API_KEY": "wuse_live_..."
}
}
}
}auth
Authentication
The MCP server reads WUSE_API_KEY from its environment. Generate keys in the dashboard. Live keys are prefixed wuse_live_…; test keys are prefixed wuse_test_….
# Generate a key
open https://dashboard.whatsapp-use.dev/keys
# Pass it via env in your MCP config
"env": { "WUSE_API_KEY": "wuse_live_..." }conventions
Conventions
A few patterns apply across every tool. Read these once and the rest of the reference becomes a lot shorter.
IDs
Every resource has a stable string ID with a typed prefix: acc_, chat_, msg_, med_, grp_.
Pagination
list_chats and list_messages return up to 100 items by default. Pass limit (max 200) and the next_cursor from a previous response to page forward, or before (a message ID or timestamp) to walk backward into history.
Phone numbers
Always use E.164 format with a leading +, e.g. +14155550198.
Timestamps
ISO 8601 in UTC. Notifications include occurred_at (when WhatsApp says it happened) and received_at (when our server saw it).
Idempotency
Tools that create or mutate accept an optional idempotency_key argument. Same key returns the same result for 24 hours.
accounts
Account & pairing tools
Every connected WhatsApp number is an account. Pair via QR code or phone sync, watch its status, and reconnect or unpair at any time.
Start a pairing session and return a QR code or phone-sync code plus a status stream.
List every account connected under your API key.
Get an account's metadata: phone number, display name, paired_at, last seen.
Get the connection status: pairing | connected | disconnected | expired | logged_out.
Force a reconnect attempt for a disconnected account.
Log out from WhatsApp Web. The owner can re-pair the same number later.
Unpair and delete the account. Stored data is purged within 30 days.
messages
Message tools
Send text, media, voice notes, locations, and contact cards. Edit within WhatsApp's 15-minute window. Delete, react, star, and forward.
Send a message to a chat. Supports text, image, document, audio, video, location, and contact types.
Get a single message by ID.
Edit a message. WhatsApp permits edits within 15 minutes of sending.
Delete a message. Pass scope='me' or scope='everyone'.
Add a reaction emoji to a message.
Remove your reaction from a message.
Star a message.
Unstar a message.
Forward a message to one or more chats.
chats
Chat & inbox tools
Every conversation — 1:1 or group — is a chat. List the inbox, page older history backward, fetch newer messages forward, mark read, archive, mute, pin.
List chats in the inbox. Supports filter (unread, archived, pinned, label), limit, and cursor.
Get a chat's metadata: type, name, participants, settings, last message.
Fetch messages in a chat. Page backward with `before` (older), forward with `after` (newer).
Open or create a 1:1 chat with a phone number.
Mark a chat read up to the latest message.
Mark a chat unread.
Archive a chat.
Move an archived chat back to the inbox.
Mute notifications for a chat.
Unmute notifications.
Pin a chat to the top of the inbox.
Unpin a chat.
Delete the chat locally. Future inbound messages will reopen the conversation.
groups
Group tools
Groups are chats with multiple participants and admin controls. Create, manage participants, rotate invite links, and update metadata.
Create a group with a name and initial participants.
Get group metadata: name, description, picture, admins, settings.
Update group name, description, or picture.
List participants with their admin status.
Add participants by phone number.
Remove a participant from a group.
Promote a participant to admin.
Demote an admin to a regular participant.
Generate or rotate the group's invite link.
Leave the group from the connected account.
contacts
Contact tools
Contacts are phone numbers the connected account knows. Check WhatsApp availability before sending, read profile metadata.
List contacts the account has interacted with.
Get a contact's profile: display name, status, picture URL.
Check whether one or more phone numbers are reachable on WhatsApp.
Get a contact's profile picture URL when visible to the account.
Get a contact's 'about' text.
media
Media tools
Upload images, audio, video, and documents to attach to messages. Download received media. Each media object has metadata and a signed URL good for 24 hours.
Upload a media file. Returns a media ID for use with send_message.
Download media as binary, or return a signed URL.
Get media metadata: mime type, size, duration, dimensions.
presence
Presence & typing tools
Signal presence (online, typing, recording) and read a contact's last-seen status when they've made it visible.
Set presence in a chat: online, typing, recording, paused.
Get a contact's presence (last seen, online status) when shared.
profile
Account profile tools
Read and update the connected WhatsApp account's profile — display name, 'about' text, and picture.
Get the connected account's profile.
Update display name or 'about' text.
Set or replace the profile picture from a media ID.
search
Search tools
Search across messages and chats. Useful for context recall and inbox analytics.
Full-text search across messages. Filter by chat, sender, type, and date range.
Search chats by name or participant.
notifications
Notifications
The MCP server pushes notifications to your agent as MCP notifications messages (no polling, no webhook setup). Subscribe to the events your agent cares about and the server streams them on the open connection.
errors
Errors
Tool errors return a JSON body with a code, a human-readable message, and optional fields for validation issues. HTTP-style status codes are surfaced for parity.