npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

mcp-evolution

v0.8.1

Published

MCP server for Evolution API (WhatsApp) with instance allowlist, tool and recipient guards

Readme

mcp-evolution

npm version license CI

TypeScript MCP server for Evolution API (WhatsApp) with an instance allowlist and server-side guards (tool allowlist, recipient allowlist, secret redaction).

Fork maintained by Francione Matias Carvalho, based on billyfranklim1/mcp-evolution (MIT).

Architecture

This server implements the Model Context Protocol:

  • Transport: stdio — the MCP host (Claude Desktop, Claude Code, etc.) spawns this process and speaks JSON-RPC over stdin/stdout.
  • Server: uses the high-level McpServer class from the official TypeScript SDK, which handles capability negotiation and session lifecycle automatically.
  • Tools: 55 tools registered via registerTool() with Zod-validated input schemas — the SDK enforces types before the handler runs.
  • Guards: every tool goes through a registry that enforces the tool allowlist, the instance allowlist and the recipient allowlist, and redacts secrets from everything returned to the client.

The API URL, API key and the set of allowed instances are fixed at startup via environment variables. The AI caller can only pick an instance from that list — it can never address an instance outside it.

Tools

Tools marked (D) are dangerous and disabled unless explicitly enabled.

Instances

| Tool | Description | |------|-------------| | list_instances | List the allowed instances (names only), the default one and, optionally, each connection state |

Message

| Tool | Description | |------|-------------| | send_text | Send a plain text message | | send_media | Send an image, video, audio, or document | | send_audio | Send a WhatsApp audio (PTT voice note) | | send_sticker | Send a sticker (webp) | | send_location | Send a location pin | | send_contact | Share one or more contacts (vCards) | | send_reaction | React to a message with an emoji | | send_poll | Send a poll message | | send_list | Send an interactive list/menu message | | send_button | Send an interactive button message | | send_status (D) | Post a WhatsApp Status (story) update |

Chat

| Tool | Description | |------|-------------| | find_chats | Find chats, optionally filtered with a Prisma-style where clause | | find_contacts | Find contacts, optionally filtered | | find_messages | Find messages by remoteJid with optional limit | | get_chat_history | Get message history for a contact or group JID | | mark_as_read | Mark one or more messages as read | | archive_chat | Archive or unarchive a chat | | delete_message (D) | Delete a message for everyone | | fetch_profile_picture | Fetch a contact's profile picture URL | | download_media | Download media from a message to a local file | | send_presence | Send a presence update (typing, recording, etc.) | | check_number | Check whether phone numbers have WhatsApp accounts |

Profile

| Tool | Description | |------|-------------| | fetch_business_profile | Fetch a contact's WhatsApp Business profile | | update_profile_name (D) | Update the instance's display name | | update_profile_status (D) | Update the instance's about/status text | | update_profile_picture (D) | Update the instance's profile picture | | remove_profile_picture (D) | Remove the instance's profile picture | | fetch_privacy | Fetch current privacy settings | | update_privacy (D) | Update privacy settings | | update_block_status (D) | Block or unblock a contact |

Group

| Tool | Description | |------|-------------| | list_groups | List all WhatsApp groups for the selected instance | | get_group_info | Get detailed info for a specific group by JID | | create_group (D) | Create a new WhatsApp group | | update_group_subject (D) | Update a group's name | | update_group_description (D) | Update a group's description | | update_group_picture (D) | Update a group's profile picture | | fetch_invite_code | Fetch the invite code/link for a group | | revoke_invite_code (D) | Revoke and regenerate a group's invite code | | accept_invite (D) | Accept a group invite by code | | send_group_invite | Send a group invite link to specific contacts | | update_participants (D) | Add, remove, promote, or demote group participants | | update_group_setting (D) | Update group settings (announcement mode, locked) | | leave_group (D) | Leave a group | | find_group_by_invite | Get group info from an invite code without joining |

Instance

| Tool | Description | |------|-------------| | connection_state | Get the current connection state of the instance | | restart_instance (D) | Restart the instance (reconnects without logging out) | | logout_instance (D) | Logout the instance (clears session) | | get_settings | Get current instance settings | | set_settings (D) | Update instance settings |

Webhook

| Tool | Description | |------|-------------| | find_webhook | Get the current webhook configuration | | set_webhook (D) | Configure the webhook |

Label

| Tool | Description | |------|-------------| | find_labels | List all labels (requires WhatsApp Business) | | handle_label | Add or remove a label from a chat |

Install & run via npx

EVOLUTION_API_URL=http://localhost:8080 \
EVOLUTION_API_KEY=your-key \
EVOLUTION_INSTANCE=your-instance \
npx mcp-evolution

Configuration

| Variable | Required | Description | |----------|----------|-------------| | EVOLUTION_API_URL | Yes | Base URL of your Evolution API (e.g. http://localhost:8080) | | EVOLUTION_API_KEY | Yes | Global API key from Evolution API config | | EVOLUTION_INSTANCE | One of these two | Single instance name (legacy / simplest mode) | | EVOLUTION_INSTANCES | One of these two | Comma-separated list of allowed instances, e.g. personal,support | | EVOLUTION_DEFAULT_INSTANCE | No | Instance used when a call omits instance (must be in EVOLUTION_INSTANCES) | | EVOLUTION_ALLOWED_TOOLS | No | Comma-separated tool names and/or groups. Unset = every non-dangerous tool | | EVOLUTION_ALLOWED_RECIPIENTS | No | Comma-separated recipient allowlist (numbers, JIDs, LIDs, group JIDs). Unset = unrestricted | | EVOLUTION_ALLOWED_RECIPIENTS__<INSTANCE> | No | Per-instance recipient allowlist; overrides the global one for that instance | | EVOLUTION_BASIC_AUTH | No | Base64 user:password sent as Authorization: Basic … (e.g. nginx in front of Evolution) | | EVOLUTION_DB_URL | No | Evolution Postgres URL, only for get_group_resolved_participants |

Invalid configuration (unknown tool names, default instance outside the list, both EVOLUTION_INSTANCE and EVOLUTION_INSTANCES set, malformed recipients…) aborts at startup with a message that never includes secret values.

Instances

  • One instance (EVOLUTION_INSTANCE=foo, or EVOLUTION_INSTANCES=foo): works exactly like before — no instance parameter is added and every call goes to foo.
  • Several instances (EVOLUTION_INSTANCES=foo,bar): every instance-bound tool gets an optional instance parameter, validated against the list (a zod enum). Omitted → EVOLUTION_DEFAULT_INSTANCE; if no default is set the call fails asking for instance. Any value outside the list is rejected before any HTTP request is made.
  • list_instances returns the configured names and which one is the default; includeState: true also queries each connection state.

Tool allowlist — EVOLUTION_ALLOWED_TOOLS

When set, only the listed tools are registered; everything else does not even show up in tools/list. Entries are tool names or groups:

| Group | Tools | |-------|-------| | @read | list_instances, connection_state, list_groups, find_chats, find_contacts, find_messages, find_labels, find_webhook, find_group_by_invite, get_chat_history, get_group_info, get_group_resolved_participants, get_settings, check_number, download_media, fetch_business_profile, fetch_invite_code, fetch_privacy, fetch_profile_picture | | @send | send_text, send_media, send_audio, send_presence, mark_as_read | | @default | every tool except the dangerous ones (what you get when the variable is unset) | | @dangerous | every dangerous tool (see below) |

Examples: @read,@send · @read,send_text · @default,send_status.

Dangerous tools (disabled by default)

These tools change account/group state irreversibly, broadcast, or can redirect traffic. They are not registered unless named explicitly in EVOLUTION_ALLOWED_TOOLS (or via @dangerous):

| Tool | Why | |------|-----| | send_status | Broadcasts to all contacts; known to disconnect every linked device (evolution-api#2196) | | delete_message | Deletes messages for everyone | | update_privacy | Changes account privacy | | update_profile_name, update_profile_status, update_profile_picture, remove_profile_picture | Change the public profile | | update_block_status | Blocks/unblocks contacts | | create_group, update_group_subject, update_group_description, update_group_picture, update_group_setting, update_participants, revoke_invite_code, accept_invite, leave_group | Change group state/membership | | restart_instance, logout_instance | Disrupt or destroy the WhatsApp session | | set_settings | Changes instance behaviour (auto-read, reject calls, always online…) | | set_webhook | Can redirect every incoming event to an arbitrary URL |

To re-enable, list them: EVOLUTION_ALLOWED_TOOLS=@default,send_status,delete_message (or @default,@dangerous for the pre-0.6 behaviour).

Recipient allowlist — EVOLUTION_ALLOWED_RECIPIENTS

When set, any tool argument that identifies a chat — number, numbers[], remoteJid, jid, groupJid, chat, participants[], statusJidList[], including nested ones such as readMessages[].remoteJid or key.remoteJid — must match the list, otherwise the call is rejected before reaching Evolution (the error names the rejected value, never the list). In addition:

  • find_chats, find_contacts and list_groups only return entries in the list; find_group_by_invite refuses groups outside it.
  • send_status requires an explicit statusJidList; accept_invite is refused.

Matching normalises both sides to digits of the part before @ (dropping a :device suffix). Accepted forms: 5511999999999, +55 (11) 99999-9999, [email protected], …@c.us, 123456789012345@lid, 120363…@g.us. A LID is a different identifier from the phone number — if a contact reaches you as @lid, list that LID too. Write Brazilian mobiles in full (55 DD 9XXXXXXXX); legacy JIDs without the extra 9 then match as well.

All groups: add *@g.us to admit every group (any …@g.us JID, for reading and sending) while direct chats stay limited to the numbers you list, e.g. 5511999999999,*@g.us. Groups must then be addressed by their full @g.us JID.

Per instance: EVOLUTION_ALLOWED_RECIPIENTS__<INSTANCE> replaces the global list for that instance. <INSTANCE> is the instance name upper-cased with every character outside A-Z0-9 replaced by _ (e.g. billy-franklim.2 → EVOLUTION_ALLOWED_RECIPIENTS__BILLY_FRANKLIM_2). Use * as the value to leave one instance unrestricted while a global list applies to the others.

Secret redaction

The API key, EVOLUTION_BASIC_AUTH (both the base64 value and the decoded user:password/password) and passwords embedded in EVOLUTION_API_URL/EVOLUTION_DB_URL are replaced by [REDACTED] in every tool result and error returned to the MCP client, including Evolution error bodies that echo request headers.

Use with Claude Code / Claude Desktop

Keep secrets out of the MCP JSON by putting them in an env file and loading it with Node's --env-file (Node ≥ 20.6):

# /path/to/credentials.env  (chmod 600)
EVOLUTION_API_URL=https://evolution.example.com
EVOLUTION_API_KEY=...
EVOLUTION_BASIC_AUTH=...

Single instance, read + basic send, one test recipient (.mcp.json or claude mcp add-json):

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": [
        "--env-file=/path/to/credentials.env",
        "/absolute/path/to/mcp-evolution/dist/index.js"
      ],
      "env": {
        "EVOLUTION_INSTANCE": "my-instance",
        "EVOLUTION_ALLOWED_TOOLS": "@read,@send",
        "EVOLUTION_ALLOWED_RECIPIENTS": "5511999999999"
      }
    }
  }
}

Several instances with a default and per-instance recipients:

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["--env-file=/path/to/credentials.env", "/absolute/path/to/mcp-evolution/dist/index.js"],
      "env": {
        "EVOLUTION_INSTANCES": "personal,support",
        "EVOLUTION_DEFAULT_INSTANCE": "personal",
        "EVOLUTION_ALLOWED_TOOLS": "@read,@send",
        "EVOLUTION_ALLOWED_RECIPIENTS__PERSONAL": "5511999999999,123456789012345@lid",
        "EVOLUTION_ALLOWED_RECIPIENTS__SUPPORT": "*"
      }
    }
  }
}

If a variable is defined both in env and in the file, Node keeps the value from env (the process environment wins). Keep secrets in the file and the guards in the JSON, where they are easy to review. With npx ("command": "npx", "args": ["mcp-evolution"]) there is no --env-file, so every variable has to go in env.

Run as a remote server (Streamable HTTP)

Set MCP_TRANSPORT=http to serve MCP over HTTP instead of stdio, so clients connect by URL and nothing runs on their machine. The server is stateless: each request gets a fresh MCP server with the same guards.

| Variable | Default | Notes | |---|---|---| | MCP_TRANSPORT | stdio | stdio or http | | MCP_AUTH_TOKEN | — | Required in HTTP mode, at least 32 characters. Clients send Authorization: Bearer <token> | | PORT | 3000 | | | HOST | 0.0.0.0 | Use 127.0.0.1 behind a reverse proxy | | MCP_HTTP_PATH | /mcp | |

GET /health answers without auth for uptime checks. Put the server behind HTTPS (nginx, Caddy) and keep the guards (EVOLUTION_ALLOWED_TOOLS, EVOLUTION_ALLOWED_RECIPIENTS) in its environment: the token only proves who is calling, the guards still decide what they can do.

Register it in Claude Code:

claude mcp add --transport http evolution https://your-host/mcp --header "Authorization: Bearer $MCP_AUTH_TOKEN"

Development

# Install dependencies
npm install

# Run in dev mode (no build step)
npm run dev

# Build TypeScript → dist/
npm run build

# Run tests
npm test

# Start from built output
npm start

Evolution API endpoints wrapped

| Tool | Method | Path | |------|--------|------| | send_text | POST | /message/sendText/{instance} | | send_media | POST | /message/sendMedia/{instance} | | send_audio | POST | /message/sendWhatsAppAudio/{instance} | | send_sticker | POST | /message/sendSticker/{instance} | | send_location | POST | /message/sendLocation/{instance} | | send_contact | POST | /message/sendContact/{instance} | | send_reaction | POST | /message/sendReaction/{instance} | | send_poll | POST | /message/sendPoll/{instance} | | send_list | POST | /message/sendList/{instance} | | send_button | POST | /message/sendButtons/{instance} | | send_status | POST | /message/sendStatus/{instance} | | find_chats | POST | /chat/findChats/{instance} | | find_contacts | POST | /chat/findContacts/{instance} | | find_messages / get_chat_history | POST | /chat/findMessages/{instance} | | mark_as_read | POST | /chat/markMessageAsRead/{instance} | | archive_chat | POST | /chat/archiveChat/{instance} | | delete_message | DELETE | /chat/deleteMessageForEveryone/{instance} | | fetch_profile_picture | POST | /chat/fetchProfilePictureUrl/{instance} | | download_media | POST | /chat/getBase64FromMediaMessage/{instance} | | send_presence | POST | /chat/sendPresence/{instance} | | check_number | POST | /chat/whatsappNumbers/{instance} | | fetch_business_profile | POST | /chat/fetchBusinessProfile/{instance} | | update_profile_name | POST | /chat/updateProfileName/{instance} | | update_profile_status | POST | /chat/updateProfileStatus/{instance} | | update_profile_picture | POST | /chat/updateProfilePicture/{instance} | | remove_profile_picture | DELETE | /chat/removeProfilePicture/{instance} | | fetch_privacy | GET | /chat/fetchPrivacySettings/{instance} | | update_privacy | POST | /chat/updatePrivacySettings/{instance} | | update_block_status | POST | /chat/updateBlockStatus/{instance} | | list_groups | GET | /group/fetchAllGroups/{instance} | | get_group_info | GET | /group/findGroupInfos/{instance} | | create_group | POST | /group/create/{instance} | | update_group_subject | POST | /group/updateGroupSubject/{instance}?groupJid= | | update_group_description | POST | /group/updateGroupDescription/{instance}?groupJid= | | update_group_picture | POST | /group/updateGroupPicture/{instance}?groupJid= | | fetch_invite_code | GET | /group/inviteCode/{instance}?groupJid= | | revoke_invite_code | POST | /group/revokeInviteCode/{instance}?groupJid= | | accept_invite | GET | /group/acceptInviteCode/{instance}?inviteCode= | | send_group_invite | POST | /group/sendInvite/{instance} | | update_participants | POST | /group/updateParticipant/{instance}?groupJid= | | update_group_setting | POST | /group/updateSetting/{instance}?groupJid= | | leave_group | DELETE | /group/leaveGroup/{instance}?groupJid= | | find_group_by_invite | GET | /group/inviteInfo/{instance}?inviteCode= | | connection_state / list_instances | GET | /instance/connectionState/{instance} | | restart_instance | POST | /instance/restart/{instance} | | logout_instance | DELETE | /instance/logout/{instance} | | get_settings | GET | /settings/find/{instance} | | set_settings | POST | /settings/set/{instance} | | find_webhook | GET | /webhook/find/{instance} | | set_webhook | POST | /webhook/set/{instance} | | find_labels | GET | /label/findLabels/{instance} | | handle_label | POST | /label/handleLabel/{instance} |

Requires Evolution API v2.

Docker — kit completo (Evolution + Postgres + Redis + servidor MCP)

The docker/ folder ships a ready-to-run stack:

cd docker
cp .env.example .env      # fill in POSTGRES_PASSWORD, EVOLUTION_API_KEY, MCP_AUTH_TOKEN, EVOLUTION_INSTANCE
docker compose --env-file .env up -d --build

Services: postgres:15-alpine, redis:7-alpine, evoapicloud/evolution-api (port 8080) and this MCP server in HTTP mode (port 8930, GET /health, Bearer-protected /mcp).

Then create the WhatsApp instance and pair a phone:

sh scripts/criar-instancia.sh     # writes qrcode-instancia.png

Full step-by-step (PT-BR), client configuration examples and troubleshooting: docker/README.md.

License

MIT — see LICENSE.

Disclaimer

Community software, not affiliated with Evolution API or any WhatsApp entity.