MCP Server

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

npx (Recommended)
Global install
Project dependency

WSAPI_API_KEY=your_api_key \
WSAPI_INSTANCE_ID=your_instance_id \
npx @wsapichat/mcp-server

npm install -g @wsapichat/mcp-server

WSAPI_API_KEY=your_api_key \
WSAPI_INSTANCE_ID=your_instance_id \
wsapi-mcp

npm install @wsapichat/mcp-server

WSAPI_API_KEY=your_api_key \
WSAPI_INSTANCE_ID=your_instance_id \
npx wsapi-mcp

Environment variables

Variable	Required	Description	Default
`WSAPI_API_KEY`	Yes	WSAPI API key for authentication	—
`WSAPI_INSTANCE_ID`	Yes	WhatsApp instance to control	—
`WSAPI_BASE_URL`	No	Custom API endpoint	`https://api.wsapi.chat`
`WSAPI_TIMEOUT`	No	HTTP timeout in milliseconds	`30000`
`WSAPI_RETRY_ATTEMPTS`	No	Retries for recoverable errors	`3`
`WSAPI_RETRY_DELAY`	No	Milliseconds between retries	`1000`
`LOG_LEVEL`	No	`error`, `warn`, `info`, or `debug`	`info`

Connect to Claude Desktop

Add the server to your Claude Desktop config file:

macOS
Windows

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"
      }
    }
  }
}

Edit %APPDATA%\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:

Category	Tools
Messaging	`whatsapp_send_text`, `whatsapp_send_media`, `whatsapp_send_document`, `whatsapp_send_sticker`, `whatsapp_send_location`, `whatsapp_send_reaction`, `whatsapp_edit_message`, `whatsapp_delete_message`
Contacts	`whatsapp_get_contacts`, `whatsapp_get_contact`, `whatsapp_create_contact`, `whatsapp_update_contact`, `whatsapp_get_contact_picture`, `whatsapp_subscribe_contact_presence`
Groups	`whatsapp_get_groups`, `whatsapp_create_group`, `whatsapp_update_group_name`, `whatsapp_manage_participants`
Chats	`whatsapp_get_chats`, `whatsapp_get_chat`, `whatsapp_set_chat_presence`, `whatsapp_archive_chat`, `whatsapp_pin_chat`
Session	`whatsapp_get_session_status`, `whatsapp_get_qr_code`, `whatsapp_get_pair_code`, `whatsapp_logout`
Instance	`whatsapp_get_instance_settings`, `whatsapp_update_instance_settings`, `whatsapp_restart_instance`, `whatsapp_update_api_key`
Account	`whatsapp_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

Authentication failures

Double-check your API key, instance status, and environment variable spelling. The startup validator prints specific missing keys.

Timeouts or flaky delivery

Increase WSAPI_TIMEOUT, WSAPI_RETRY_ATTEMPTS, or WSAPI_RETRY_DELAY for congested networks.

Claude Desktop can't see the server

Ensure the server runs in the same user session, verify the config path for your OS, and restart Claude after edits.

Need more context?

Set LOG_LEVEL=debug to dump request/response metadata (media payloads remain redacted).

GitHub

github.com/wsapi-chat/wsapi-mcp

Getting Started

Basics

SDKs & Libraries

Integrations

What you get

Requirements

Installation

Environment variables

Connect to Claude Desktop

Tool catalog

Common workflows

Troubleshooting

GitHub

​What you get

​Requirements

​Installation

​Environment variables

​Connect to Claude Desktop

​Tool catalog

​Common workflows

​Troubleshooting

​GitHub

What you get

Requirements

Installation

Environment variables

Connect to Claude Desktop

Tool catalog

Common workflows

Troubleshooting

GitHub