mcp-evolution

TypeScript MCP server for Evolution API (WhatsApp) with instance pinning.

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: 50 tools registered via registerTool() with Zod-validated input schemas — the SDK enforces types before the handler runs.

All three connection parameters (API URL, API key, instance name) are pinned at startup via environment variables. The AI caller cannot switch instances mid-conversation.

Tools

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`	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`	Delete a message for everyone
`fetch_profile_picture`	Fetch a contact's profile picture URL
`download_media`	Download media from a message as base64
`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`	Update the instance's display name
`update_profile_status`	Update the instance's about/status text
`update_profile_picture`	Update the instance's profile picture
`remove_profile_picture`	Remove the instance's profile picture
`fetch_privacy`	Fetch current privacy settings
`update_privacy`	Update privacy settings
`update_block_status`	Block or unblock a contact

Group

Tool	Description
`list_groups`	List all WhatsApp groups for the pinned instance
`get_group_info`	Get detailed info for a specific group by JID
`create_group`	Create a new WhatsApp group
`update_group_subject`	Update a group's name
`update_group_description`	Update a group's description
`update_group_picture`	Update a group's profile picture
`fetch_invite_code`	Fetch the invite code/link for a group
`revoke_invite_code`	Revoke and regenerate a group's invite code
`accept_invite`	Accept a group invite by code
`send_group_invite`	Send a group invite link to specific contacts
`update_participants`	Add, remove, promote, or demote group participants
`update_group_setting`	Update group settings (announcement mode, locked)
`leave_group`	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`	Restart the instance (reconnects without logging out)
`logout_instance`	Logout the instance (clears session)
`get_settings`	Get current instance settings
`set_settings`	Update instance settings

Webhook

Tool	Description
`find_webhook`	Get the current webhook configuration
`set_webhook`	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`	Yes	Instance name created in Evolution API

Copy .env.example to .env for local development.

Use with Claude Desktop / Claude Code

Add to ~/.claude/claude_desktop_config.json or project .mcp.json:

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["mcp-evolution"],
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "your-evolution-api-key",
        "EVOLUTION_INSTANCE": "your-instance-name"
      }
    }
  }
}

Or point directly at the built binary if running from a local checkout:

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-evolution/dist/index.js"],
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "your-evolution-api-key",
        "EVOLUTION_INSTANCE": "your-instance-name"
      }
    }
  }
}

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`	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.

License

MIT — see LICENSE.

Disclaimer

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

mcp-evolution

mcp-evolution

Architecture

Tools

Message

Chat

Profile

Group

Instance

Webhook

Label

Install & run via npx

Configuration

Use with Claude Desktop / Claude Code

Development

Evolution API endpoints wrapped

License

Disclaimer

Reviews