MCP Server

The WSAPI MCP Server exposes 101 WhatsApp tools to any Model Context Protocol (MCP) compatible assistant, letting LLMs send messages, manage contacts and groups, and manage WhatsApp sessions without leaving the conversation.

What you get

WhatsApp coverage for messages, contacts, groups, communities, chats, users, calls, newsletters, status, media and sessions (not Cloud Account or OSS admin 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 20.19 or later, through Node.js 24
npm 9 or later
A WSAPI Cloud or self-hosted OSS instance (pair it before messaging)
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`
`WSAPI_ENABLED_CATEGORIES`	No	Comma-separated tool categories; empty enables all	empty
`WSAPI_ENABLED_TOOLS`	No	Tool names to include, in addition to enabled categories; both filters empty enables all	empty
`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 101 WhatsApp tools by default. Use your client’s tools/list operation for the complete catalog and input schemas, or filter the catalog with the environment variables above.

Category	Example tools
Messaging	`whatsapp_send_text`, `whatsapp_send_image`, `whatsapp_send_video`, `whatsapp_send_audio`, `whatsapp_send_document`, `whatsapp_send_sticker`
Contacts	`whatsapp_get_contacts`, `whatsapp_create_contact`, `whatsapp_sync_contacts`, `whatsapp_block_contact`
Groups	`whatsapp_get_groups`, `whatsapp_create_group`, `whatsapp_update_group_name`, `whatsapp_update_group_participants`
Chats	`whatsapp_get_chats`, `whatsapp_get_chat`, `whatsapp_set_chat_presence`, `whatsapp_archive_chat`
Session	`whatsapp_get_session_status`, `whatsapp_get_qr_code`, `whatsapp_get_qr_code_image`, `whatsapp_get_pair_code`
Media	`whatsapp_download_media`

QR images are returned as MCP image content. Downloads are embedded binary resources with base64 blob data and a MIME type; they are not decoded as JSON or UTF-8 text.

Common workflows

Verify connectivity — call tools/list in your MCP client and confirm the WSAPI catalog is returned
Send a message — use whatsapp_send_text with to and text fields
Share media — use whatsapp_send_image (or the specific media tool) with url or base64 data and optional mimeType
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