WhatsApp MCP

An MCP server that gives Claude read and write access to WhatsApp, through a self-hosted Evolution API gateway. Dependency-free: one file, Node's built-in fetch, stdio transport.

Your number stays linked on your own machine. No third party sees the messages.

Tools

Related MCP server: Evolution API MCP Server

Requirements

A running Evolution API instance with a linked WhatsApp number. This server is only a client; it does not start or manage the gateway.

Configure

All configuration is environment variables:

Register it with Claude Code:

claude mcp add whatsapp -s user \
  -e EVO_APIKEY=your-key \
  -e EVO_URL=http://localhost:8080 \
  -e EVO_INSTANCE=primary \
  -- node /path/to/whatsapp-mcp/server.js

claude mcp list   # expect: whatsapp ... Connected

Restart Claude Code afterwards. Tool lists are read once at session start, so a newly added server (or a newly added tool) will not appear in a session that was already running.

Test

EVO_APIKEY=your-key npm test

An integration check against the live gateway, no mocks: it spawns a real server process, finds a recent image on its own, and asserts get_media returns decoded image bytes and writes them to disk. Pin a specific message with WA_TEST_MESSAGE_ID if you would rather not have it search.

Notes

• get_media inlines images up to 3.5 MB; anything larger, and any non-image, is saved to disk and the path is returned instead.

• Downloads are pruned after 24 hours so a chat full of photos cannot quietly grow into a disk problem.

• Media only downloads while it is still on WhatsApp's servers. Very old attachments can come back empty.