Documentation

Quickstart

Three steps, about two minutes.

# Claude Code
claude mcp add --transport http whatsapp https://wacli.me/mcp \
  --header "Authorization: Bearer <your-token>"

# Config file form, understood by most clients
{
  "mcpServers": {
    "whatsapp": {
      "type": "http",
      "url": "https://wacli.me/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Every request to /mcp carries a bearer token:

Authorization: Bearer 9f3c…<64 hex characters>

The token resolves to exactly one account store. There are no user names, no sessions and no cookies — a request either carries a valid token or is refused with 401 before anything reads a database.

Tokens are compared in constant time and never written to logs. If one leaks, ask for a rotation: the old value stops working the moment the new one is issued, and clients only need the header updated.

Or skip the token entirely

The server is also an OAuth 2.1 authorization server, which is what most MCP clients try first. Add https://wacli.me/mcp with no credentials: the client discovers the authorization server from the 401, registers itself, opens a browser, you scan the WhatsApp QR code there, and the client collects its own token. Nothing is copied by hand.

Endpoint	Purpose
/.well-known/oauth-protected-resource	Points at the authorization server
/.well-known/oauth-authorization-server	Metadata: endpoints, PKCE support
/oauth/register	Dynamic client registration (RFC 7591)
/oauth/authorize	Shows the linking page, returns a code
/oauth/token	Exchanges code + PKCE verifier for a token

PKCE with S256 is required, codes are single-use and expire after five minutes, and a redirect URI must match the client's registration exactly.

Stateless is deliberate. Every request builds its own server object bound to one store, so a bug in request handling cannot leak state between accounts, and a restart never invalidates a session someone was in the middle of.

WhatsApp identifies conversations with a JID, and every tool that takes a chat argument expects one:

• [email protected] — a person, addressed by phone number
• 123456789012345678@lid — a linked id, the pseudonymous form most contacts have had since 2024
• [email protected] — a group

You rarely type one by hand. Call list_chats or search_contacts with a name, take the jid field from the result, and pass it on. The send_message tool additionally accepts a plain phone number or an exact chat name and resolves it itself.

Tool failures are returned as tool errors rather than protocol errors on purpose: an assistant can read the message, correct the argument and try again, which is what you want when it guessed a JID wrong.