Skip to main content
Glama
wsti-studio

WhatsApp MCP

by wsti-studio
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

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

Tool

What it does

connection_status

Is the number linked and online.

list_chats

Recent chats, newest first, with JIDs and unread counts.

list_messages

Messages in one chat. Each carries an id; attachments carry a media_type.

get_media

Download the attachment on a message. Images come back viewable inline.

search_contacts

Match contacts by name or number substring.

check_number

Is a phone number registered on WhatsApp.

list_groups

Groups this number belongs to, with JIDs.

send_message

Send a text message. The only tool with an outbound side effect.

reconnect

Returns a pairing QR when the link has dropped.

restart_instance

Bounce a stuck instance. Does not unlink the number.

Related MCP server: mcp-zap

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:

Variable

Default

Meaning

EVO_APIKEY

(required)

Global API key, AUTHENTICATION_API_KEY in Evolution's .env.

EVO_URL

http://localhost:8080

Base URL of the Evolution API server.

EVO_INSTANCE

primary

Instance name for your number.

EVO_MEDIA_DIR

media/ beside server.js

Where get_media saves attachments.

EVO_QR_PATH

<instance>-qr.png beside server.js

Where reconnect writes the pairing QR.

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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

  • WhatsMCP: MCP for WhatsAppAOAuth
    com.whatsmcp.app

    WhatsMCP connects Claude and other MCP-compatible AI agents directly to WhatsApp. Send and receive text, images, documents, and voice notes; manage groups (create, add/remove members, promote admins); look up contacts and profiles; follow channels; and read call and message history — all through a standard MCP interface. For voice use cases, WhatsMCP offers SIP-based calling plans (inbound-only, or full inbound/outbound) so AI voice agents can answer and place WhatsApp calls, plus low-latency WebSocket integrations with voice agent providers like ElevenLabs. Multiple WhatsApp accounts can be paired and managed per workspace, with webhook support for real-time inbound message delivery to your own infrastructure.

    App AutomationCommunicationSocial Media
    361
  • whatsappOAuth
    me.wacli

    Your own WhatsApp as an MCP server: read, search and send from any MCP client.

    CommunicationApp Automation
    1
  • Remote Desktop CommanderOAuth
    app.desktopcommander

    Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer

    Shell AccessOS Automation
    265
  • whatsappOAuth
    com.corapilot

    Let Claude or ChatGPT search, read and send your WhatsApp messages over MCP. OAuth sign-in.

    CommunicationApp Automation
    1

Related MCP Servers

  • MCP Evolution API

    aiteks-ltda
    A
    license
    C
    quality
    D
    maintenance
    A Model Context Protocol server that enables Claude to interact with WhatsApp through the Evolution API, allowing for message sending, contact management, group operations, and WhatsApp instance administration.
    1
    33 npm
    33
    MIT

  • mcp-zap

    Joaquim-Salles
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server for sending and receiving WhatsApp messages through Evolution API, enabling management of instances, messages, and chats directly from Claude Code.
    -

  • WhatsApp MCP Server

    ydmw74
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that connects Claude and other LLM clients to WhatsApp via the Baileys library. Enables sending and receiving messages, listing chats, downloading media, and more.
    6 npm
    MIT

  • mcp-whatsapp-claude

    PedroSodrr10
    A
    license
    Not graded
    quality
    C
    maintenance
    A local MCP server that connects WhatsApp to Claude via QR code, enabling chat listing, message retrieval, and sending with automatic rate limiting for anti-ban protection.
    35 npm
    MIT