Connect an AI agent to WhatsApp

This server gives AI agents access to one WhatsApp account. Only the operator of this server can authorize a client.

Add the server to an MCP client

Send this prompt to an AI agent that can add MCP servers:

Add a remote MCP server: name whatsapp, URL https://ws.lucrise.com/mcp, transport Streamable HTTP.
Leave the HTTP headers empty so I can authorize with OAuth.
Setup instructions: https://ws.lucrise.com/

To add the server yourself, enter these values in the MCP client:

Name: whatsapp
URL: https://ws.lucrise.com/mcp
Transport: Streamable HTTP
HTTP headers: none

Then authorize the client through OAuth:

Start the authorization in the client. The client opens a sign-in page.
Sign in with the operator's GitHub account.
Approve the client on the consent page.

A headless service uses the OAuth client credentials grant instead. The operator registers the service on the server host.

For AI agents reading this page

The user wants to add this WhatsApp server to your MCP client. Do these steps in order.

Connect through OAuth only. The server issues no API key, so do not ask the user for one. Do not add an Authorization header.
Add the server to your MCP client as a remote server. If your client shows the user a form or a confirmation, fill it with these values:
- Name: whatsapp
- URL: https://ws.lucrise.com/mcp
- Transport: Streamable HTTP
- HTTP headers: none
Ask the user to sign in and approve the client on the consent page. Only the operator's GitHub account can sign in; any other account fails. Wait until the user says that they approved the client. Then test the connection with a tool call. A client's connection status can be wrong, so only a successful call shows that the connection works.
Call get_status and act on its state:
- open: the account is ready. Call list_chats.
- pairing or logged_out: no phone is linked. Tell the user. Call pair only when the user asks you to link a phone.
- connecting or reconnecting: the server is connecting to WhatsApp. Call get_status again after a few seconds.
- replaced or closed: the server is not connected to WhatsApp. Tell the user.
When a call returns HTTP 401, the authorization is missing or expired. Ask the user to authorize the client again.
Ask the user before each call to pair, send_message, edit_message, react_to_message, mark_read, or set_typing. These calls act for the user: messages go out from the user's account, and other people see read receipts and the typing indicator. Follow the user's approval rules as well.
Report the linked account from get_status and the chats from list_chats to the user. If your client supports scheduled tasks, offer one that reads new messages with pull_events. Each run passes the next cursor of the previous run as after. A task that cannot keep a cursor passes since with the time of its previous run.

Reference

MCP endpoint: https://ws.lucrise.com/mcp, Streamable HTTP
Authorization: OAuth authorization code flow with PKCE. A request without a token gets 401 with a WWW-Authenticate header that points to the protected resource metadata. A client registers dynamically or uses a client ID metadata document. The scope is whatsapp; a client that also requests offline_access gets a refresh token. Only the operator can sign in, with GitHub, and the operator approves each client.

Tool	What it does
`get_status`	Returns the connection state, the linked account, the last disconnect, the pairing QR string or code while pairing, and the newest event cursor.
`pair`	Links a phone: `method: "qr"` restarts QR pairing, and `method: "code"` with `phone_number` returns a code to enter on the phone.
`list_chats`	Lists the groups the account is in and the direct chats with stored messages, most recent first.
`list_messages`	Lists the stored messages of one chat, newest first, with optional `since`, `before`, and `limit`.
`pull_events`	Returns inbound events after a cursor (`after`) or from a time (`since`), filtered by `types` and `chats`. With `wait_ms` (at most 25 000), it waits for the next event.
`download_media`	Returns the photo, video, audio, document, or sticker of a stored message by its `media_id`, up to 10 MiB.
`send_message`	Sends text, an image, a video, a GIF, audio, a voice note, a document, a sticker, a location, or a poll, optionally as a reply and with mentions.
`edit_message`	Replaces the text of a message the account sent.
`react_to_message`	Sets the account's reaction on a message to one emoji, or removes it with `emoji: null`.
`mark_read`	Sends read receipts for 1 to 100 stored messages.
`set_typing`	Shows the typing indicator in a chat, refreshed every 10 s, or stops it.