- URL:
http://<host>:3000<APP_BASE_PATH>/mcp(defaulthttp://localhost:3000/mcp) - Enabled by default. Disable with
MCP_ENABLED=falseor--mcp-enabled=false. - Stateless: no session handshake to keep alive between calls.
Upgrading from an older release? The standalone
./whatsapp mcp command and its SSE endpoint on port 8080 (/sse) are gone. Run ./whatsapp rest and point clients at /mcp. The old one-tool-per-operation set was replaced by the consolidated tools below.Connect a client
/mcp sits behind the same Basic Auth as the REST API. Send the Authorization header, plus X-Device-Id if you run more than one device:
YWRtaW46Y2hhbmdlbWU= is base64("admin:changeme"); generate yours with echo -n 'user:pass' | base64. Omit Authorization if Basic Auth is off, and X-Device-Id if there is only one device.
The exact config format depends on the client. If a client can only launch stdio servers, use a bridge such as mcp-remote.
Tools
GOWA exposes seven tools. Each takes atype (send) or action (all others) argument that selects the operation.
Notes on arguments:
whatsapp_sendalways needstypeandphone. Media is sent by URL only (image_url,video_url,audio_url,file_url,sticker_url); MCP cannot upload local files.linkneedslinkandcaption;forwardneedsmessage_id.whatsapp_sendaccepts the schedule fields (scheduled_at,timezone,recurrence,weekdays,day_of_month,end_at,occurrence_limit). Manage the result withwhatsapp_schedule(get,pause,resumeandcancelneedschedule_id).whatsapp_messageneedsphone(the chat) andmessage_id;editalso needsmessage.- On GOWA
mainafter v9.9.0,whatsapp_messagewithaction: "edit"acceptsmedia_type: "image"ormedia_type: "document"to replace a caption. Match the original media type and omitlink. See Edit a caption. whatsapp_chat:get_messagesneedschat_jid;archiveneedschat_jidandarchived.whatsapp_app:login_codeneedsphone.
HTTP_PROXY or HTTPS_PROXY. Uploads from local files require the REST API.
Your MCP client shows the full input schema of each tool. The HTTP endpoint accepts POST and DELETE. GET SSE streaming is disabled.
Device selection
Each call resolves its device in this order:- The
device_idargument on the tool call. - The
X-Device-Idheader on the MCP connection. - The only registered device, when exactly one exists.
device identification required: set the X-Device-Id header or pass device_id. See Multi-device.
Remote clients with OAuth
Hosted clients such as Claude custom connectors cannot attach a Basic Auth header. For them, GOWA can run an OAuth 2.1 authorization server for/mcp. It is off by default.
APP_BASIC_AUTHmust be set: the authorization page signs users in with those same accounts. Startup fails without it.- Issuer and resource must be the public HTTPS URLs clients see, not internal addresses like
http://gowa:3000. - With OAuth on,
/mcpaccepts a Bearer token or Basic Auth. Tokens are not accepted on REST or UI routes. - Clients register themselves (RFC 7591 dynamic client registration). Registration bodies are limited to 16 KiB and each redirect URI to 2 KiB. Registrations are limited to 40 per hour and 1,000 stored clients; unused ones are pruned after 24 hours.
- PKCE
S256is mandatory. Codes expire after 5 minutes, access tokens after 1 hour; refresh tokens rotate, and reusing an old one revokes the whole token family. Only SHA-256 hashes of tokens are stored, inMCP_OAUTH_DB_URI(defaultfile:storages/oauth.db).
localhost callbacks require an explicit port and an exact match. Other redirects require HTTPS. The OAuth resource is bound to the canonical MCP URL; token requests can omit it, but a supplied value must match. Successful authorization responses include iss.
Expired codes and tokens are pruned during OAuth writes. Rotated refresh-token hashes remain while needed to detect replay against a live family, for at most one further refresh-token lifetime of 30 days. Deleting or replacing the OAuth database invalidates existing clients and grants.
Endpoints, relative to the issuer: /oauth/authorize, /oauth/token, /oauth/register. Discovery metadata uses path-insertion well-known URLs at the domain root, so with APP_BASE_PATH=/gowa your proxy must route:
https://gowa.example.com/mcp as a custom connector and sign in with an APP_BASIC_AUTH account.
