Skip to main content
The WSAPI MCP Server exposes 60+ WSAPI-powered tools to any Model Context Protocol (MCP) compatible assistant, letting LLMs send messages, manage contacts and groups, and administer WhatsApp instances without leaving the conversation.

​
What you get

  • Full coverage for messaging, contact, group, chat, session, instance, and account operations
  • Secure credential handling with runtime validation via Zod schemas
  • Built-in health check, structured logging, and graceful shutdown helpers
  • Drop-in compatibility with Claude Desktop and other MCP clients

​
Requirements

  • Node.js 18 or later
  • npm 9 or later
  • Active WSAPI subscription with a paired instance
  • WSAPI API key and instance ID

​
Installation

​
Environment variables

VariableRequiredDescriptionDefault
WSAPI_API_KEYYesWSAPI API key for authentication—
WSAPI_INSTANCE_IDYesWhatsApp instance to control—
WSAPI_BASE_URLNoCustom API endpointhttps://api.wsapi.chat
WSAPI_TIMEOUTNoHTTP timeout in milliseconds30000
WSAPI_RETRY_ATTEMPTSNoRetries for recoverable errors3
WSAPI_RETRY_DELAYNoMilliseconds between retries1000
LOG_LEVELNoerror, warn, info, or debuginfo

​
Connect to Claude Desktop

Add the server to your Claude Desktop config file:
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "wsapi": {
      "command": "npx",
      "args": ["@wsapichat/mcp-server"],
      "env": {
        "WSAPI_API_KEY": "your_api_key_here",
        "WSAPI_INSTANCE_ID": "your_instance_id_here"
      }
    }
  }
}
For a global install, replace "command": "npx" and "args" with "command": "wsapi-mcp".

​
Tool catalog

The server registers every tool exposed by WSAPI:
CategoryTools
Messagingwhatsapp_send_text, whatsapp_send_media, whatsapp_send_document, whatsapp_send_sticker, whatsapp_send_location, whatsapp_send_reaction, whatsapp_edit_message, whatsapp_delete_message
Contactswhatsapp_get_contacts, whatsapp_get_contact, whatsapp_create_contact, whatsapp_update_contact, whatsapp_get_contact_picture, whatsapp_subscribe_contact_presence
Groupswhatsapp_get_groups, whatsapp_create_group, whatsapp_update_group_name, whatsapp_manage_participants
Chatswhatsapp_get_chats, whatsapp_get_chat, whatsapp_set_chat_presence, whatsapp_archive_chat, whatsapp_pin_chat
Sessionwhatsapp_get_session_status, whatsapp_get_qr_code, whatsapp_get_pair_code, whatsapp_logout
Instancewhatsapp_get_instance_settings, whatsapp_update_instance_settings, whatsapp_restart_instance, whatsapp_update_api_key
Accountwhatsapp_get_account_info, whatsapp_set_account_name, whatsapp_set_account_picture, whatsapp_set_account_presence, whatsapp_set_account_status

​
Common workflows

  • Verify connectivity — call list_tools in your MCP client and confirm the WSAPI catalog is returned
  • Send a message — use whatsapp_send_text with to and message fields
  • Share media — use whatsapp_send_media with Base64 payload and MIME type
  • Manage sessions — use whatsapp_get_qr_code or whatsapp_get_pair_code when the phone link expires

​
Troubleshooting

Double-check your API key, instance status, and environment variable spelling. The startup validator prints specific missing keys.
Increase WSAPI_TIMEOUT, WSAPI_RETRY_ATTEMPTS, or WSAPI_RETRY_DELAY for congested networks.
Ensure the server runs in the same user session, verify the config path for your OS, and restart Claude after edits.
Set LOG_LEVEL=debug to dump request/response metadata (media payloads remain redacted).

​
GitHub

github.com/wsapi-chat/wsapi-mcp