MCP Wassenger WhatsApp API Connector

🚀 Supercharge your WhatsApp automation driven by AI! Send messages, summarize conversations, and manage chats using natural language from your favorite AI assistant like ChatGPT, Claude, or custom AI agents.

✨ Easily integrateWassenger WhatsApp API with any MCP-powered AI client including ChatGPT, VS Code Copilot, Claude Desktop, Cursor, Windsurf and many more!

💬 Transform how you communicate - automate responses, analyze chat patterns, and manage customer conversations at scale, manage WhatsApp chats and groups, everything through simple conversational text or voice commands with your AI assistant.

👉 Read the blog post introducing Wassenger MCP server

⚠️ Note: You only need to use this package if your MCP client does not support HTTP streaming (previously known as SSE connection). To use a remote HTTP connection read these instructions.

About
Example prompts
HTTP streaming usage
MCP Tools Supported
Usage
Troubleshooting
Debugging
License

About

Wassenger is a versatile WhatsApp Team Chat and API solution for business messaging to automate anything on WhatsApp.

Check out the API documentation and examples here

Product update: 🚀 Automate anything on WhatsApp with our new No-Code solution Wassenger Flows ⚡✨

Example prompts

Chat with your WhatsApp conversations from any AI clients or agentic tool integration.

Here are various prompts you can use with any AI assistant to interact with WhatsApp through the Wassenger MCP connector:

📱 Basic Messaging & Communication

"Send a WhatsApp message to +1234567890 saying 'Hello! How are you today?'"
"Send a message to the contact named 'John Smith' with the text 'Meeting confirmed for 3 PM'"
"Send an urgent message to +44123456789: 'Please call me back ASAP'"
"Send a WhatsApp message with an image from [URL] to [phone-number]"
"Reply to message [message-id] in chat [chat-id] with 'Thanks for your feedback!'"

📊 Conversation Analysis & Insights

"Summarize my last 10 WhatsApp messages with +1555123456"
"Analyze the conversation tone in my chat with the Marketing Team group"
"Show me the key topics discussed in my conversation with Sarah over the past week"
"Count how many messages I've received today from all contacts"
"Search for messages containing 'invoice' in chat [chat-id]"
"Generate chat activity report grouped by day for this month"

👥 Group & Team Management

"Create a WhatsApp group called 'Team Updates' with participants +1234567890, +0987654321"
"How many participants are in the 'Project Team Alpha' WhatsApp group?"
"List all members of my 'Family Chat' group"
"Add +1234567890 to WhatsApp group [group-id]"
"Make +1234567890 an admin in group [group-id]"
"Get the invite link for group [group-id]"

⏰ Message Scheduling & Automation

"Schedule a message to +1234567890 saying 'Happy Birthday!' to be sent tomorrow at 9 AM"
"Set up a reminder message for the team group about the meeting next Friday at 2 PM"
"Set up auto-replies for messages received outside business hours (9 AM - 5 PM)"
"Create a workflow: when someone messages 'INFO', automatically send our company brochure"

🔍 Contact & Device Management

"Check if the phone number +1555987654 is a valid WhatsApp number"
"What WhatsApp numbers do I have connected to Wassenger?"
"Show me the status of all my WhatsApp devices"
"Get the profile information for contact +1234567890"
"Show me all my recent contacts from the past month"

📈 Analytics & Reporting

"Generate a report of my most frequent WhatsApp contacts this month"
"Show me my busiest WhatsApp conversation days this week"
"Which agent responds fastest to customer inquiries?"
"Show me chat volume trends over the last 30 days"
"Count unread messages across all my chats"
"Find customers who haven't interacted in the last 60 days"

🔔 Status & Monitoring

"Check the delivery status of my last message to +1234567890"
"Show me all failed message deliveries from today"
"Monitor if my contact +1555123456 has read my recent messages"
"Post 'Working on exciting new features!' as my WhatsApp status"

🔄 Bulk Operations & Campaigns

"Send the same announcement to all members of my 'Team Updates' group individually"
"Broadcast a holiday greeting to my top 10 most contacted numbers"
"Create a campaign called 'Welcome Series' to send 'Welcome to our service!' to multiple contacts"
"Start campaign [campaign-id] and check its delivery status"

🎯 Smart Business Automation

"Create a label called 'VIP Customer' with red color and apply it to important chats"
"Assign chat [chat-id] to agent [agent-id]"
"Show me all chats with the 'support' label"
"Analyze sentiment in customer support conversations and flag negative ones"
"Generate a CSV report of all chats with their last activity"
"Find all unread messages in my WhatsApp chats"

🔐 Account & File Management

"Show me my current Wassenger account usage and limits"
"Upload an image from [image-url] to use in WhatsApp messages"
"List all uploaded files tagged as 'marketing'"
"Export all contacts from device [device-id] to JSON"

These prompts cover real-world scenarios for businesses using WhatsApp for customer service, marketing, team collaboration, and automation through the Wassenger platform.

HTTP streaming usage

If your MCP client supports HTTP streaming (previously known as Server-Sent Events or SSE transport), you can connect directly to the Wassenger MCP server without installing this package. This is the preferred method as it's faster and requires no local setup.

Supported Clients

Most modern MCP clients support HTTP streaming, including:

Claude Desktop (latest versions)
VS Code Copilot with MCP extension
Cursor (v0.48.0+)
Windsurf
OpenAI Responses API
ChatGPT (Pro users have access, soon more users)

Claude Desktop Configuration

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "wassenger": {
      "type": "http",
      "url": "https://api.wassenger.com/mcp?key=YOUR_WASSENGER_API_KEY"
    }
  }
}

Or using environment variables:

{
  "mcpServers": {
    "wassenger": {
      "type": "http",
      "url": "https://api.wassenger.com/mcp?key=${WASSENGER_API_KEY}",
      "env": {
        "WASSENGER_API_KEY": "your-api-key-here"
      }
    }
  }
}

VS Code Copilot Configuration

In VS Code settings (JSON format):

{
  "mcp.servers": {
    "wassenger": {
      "url": "https://api.wassenger.com/mcp?key=YOUR_WASSENGER_API_KEY",
      "transport": "http-streaming"
    }
  }
}

Benefits of HTTP Streaming

✅ No local installation required
✅ Faster connection times
✅ Automatic updates - always uses the latest server version
✅ Better reliability - no Node.js dependency issues
✅ Simpler configuration - just a URL

Getting Your API Key

Sign up at Wassenger.com
Go to your API settings
Copy your API key
Replace YOUR_WASSENGER_API_KEY in the configuration above

MCP Tools Supported

The Wassenger MCP server provides comprehensive WhatsApp automation tools organized into functional categories. All tools use action-based parameters for LLM-friendly interactions:

📱 Core Messaging & Communication

manage_whatsapp_messages - Universal message sending with 11 action types: text, media, location, contact, poll, event, scheduled, live, expiring, agent, and template messaging
manage_whatsapp_message_interactions - Message interactions: reply, forward, reaction, and poll voting
get_whatsapp_chat_messages - Comprehensive message retrieval: recent, search, date range, by sender, by type, by ID, advanced search, thread context, and media filtering
analyze_whatsapp_chat_messages - Message analytics: statistics, delivery status tracking, and data export in multiple formats

💬 Chat & Conversation Management

get_whatsapp_chats - Universal chat retrieval with 9 actions: recent, unread, by status, assigned, by contact type, by ID, search, archived, and date range filtering
analyze_whatsapp_chats - Chat analytics and export with comprehensive statistics and data export capabilities
search_whatsapp_chats_by_name - Quick chat search by contact name, group name, or channel name

👥 Group & Team Management

manage_whatsapp_groups - Complete group operations: search, create, update, join, leave, invite management with 8 action types
manage_whatsapp_group_participants - Participant management: add, remove, promote, demote, approval workflow with 7 action types
manage_whatsapp_team - Team member management: search, create, update, delete, device access control with 7 action types
manage_whatsapp_departments - Department organization: list, create, update, delete with agent assignments and visual customization

📺 Channel & Broadcasting

manage_whatsapp_channels - Channel lifecycle management: list, create, update, search, join, leave, image updates with 9 action types
manage_whatsapp_channel_messages - Channel message retrieval with filtering and pagination
manage_whatsapp_status - WhatsApp Status (Stories) management: get, publish, schedule with media support and advanced timing

🔄 Campaign & Bulk Operations

manage_whatsapp_campaigns - Bulk messaging campaigns: search, create, update, start, stop, delete with 7 action types
manage_whatsapp_campaign_contacts - Campaign recipient management: search, add, remove contacts with filtering options
manage_whatsapp_queue - Message queue control: status monitoring, queue management, bulk deletion with 3 action types

📱 Device & Account Management

get_whatsapp_devices - Device listing with advanced filtering: status, session, search, active/online filtering
get_whatsapp_device_details - Detailed device information: configuration, session status, metrics, and insights
health_check - Comprehensive system health check for MCP server and connected WhatsApp devices

👤 Contact & Label Management

manage_whatsapp_contacts - Contact CRUD operations: list, get, create, update, delete, bulk operations, metadata management with 8 action types
manage_whatsapp_contact_actions - Contact blocking: block and unblock operations
manage_whatsapp_labels - Label management: list, create, update, delete with color-coded organization

📁 File & Media Management

search_whatsapp_outbound_files - Uploaded file search with advanced filtering by type, size, date, tags, and metadata
search_whatsapp_chat_files - Received file search from WhatsApp chats with comprehensive filtering options

🔧 System & Utilities

ping - Basic connectivity test with server status and response time measurement

📊 Analytics & Insights

All tools include comprehensive analytics capabilities:

Message delivery tracking and statistics
Chat activity analysis and reporting
Device performance metrics and monitoring
Campaign analytics and success tracking
Team productivity insights and reporting

Each tool supports extensive filtering, pagination, sorting, and export capabilities, making them perfect for both manual operations and automated workflows through AI assistants.

Usage

All the most popular MCP clients (Claude Desktop, VS Code Copilot, Cursor, Windsurf...) use the following config format:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-wassenger",
        "api-key-goes-here"
      ]
    }
  }
}

Custom Headers

To bypass authentication, or to emit custom headers on all requests to your remote server, pass --header CLI arguments:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-wassenger",
        "${WASSENGER_API}"
      ],
      "env": {
        "WASSENGER_API": "..."
      }
    },
  }
}

Note: Cursor and Claude Desktop (Windows) have a bug where spaces inside args aren't escaped when it invokes npx, which ends up mangling these values. You can work around it using:

{
  // rest of config...
  "args": [
    "mcp-wassenger",
    "${WASSENGER_API}"
  ],
  "env": {
    "WASSENGER_API": "<wassenger-api-get-here>"
  }
},

Usage as a tool in OpenAI

Here's how you can use the Wassenger MCP server as a tool with the OpenAI JavaScript client:

import OpenAI from 'openai';

const wassengerKey = process.env.WASSENGER_API_KEY || 'wassenger-api-key-here'

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// Example: Send a WhatsApp message using OpenAI's new Responses API with MCP
const response = await openai.responses.create({
  model: 'o4-mini',
  tools: [
    {
      type: 'mcp',
      server_label: 'wassenger',
      server_url: `https://api.wassenger.com/mcp?key=${wassengerKey}`,
      require_approval: 'never'
    }
  ],
  input: 'Send a WhatsApp message to +1234567890 saying "Hello from AI!"'
});

console.log('Response:', response);

Make sure to install the required dependencies:

npm install openai

And set your environment variables:

export OPENAI_API_KEY="your-openai-api-key"
export WASSENGER_API_KEY="your-wassenger-api-key"

This approach uses OpenAI's new Responses API with MCP integration, which automatically handles tool discovery, execution, and communication with the Wassenger MCP server without requiring manual MCP client setup.

Flags

If npx is producing errors, consider adding -y as the first argument to auto-accept the installation of the mcp-wassenger package.

      "command": "npx",
      "args": [
        "-y"
        "mcp-wassenger",
        "API_KEY_GOES_HERE"
      ]

To force npx to always check for an updated version of mcp-wassenger, add the @latest flag:

      "args": [
        "mcp-wassenger@latest"
      ]

To change which port mcp-wassenger listens for an OAuth redirect (by default 3334), add an additional argument after the server URL. Note that whatever port you specify, if it is unavailable an open port will be chosen at random.

      "args": [
        "mcp-wassenger",
        "API_KEY_GOES_HERE"
      ]

To enable detailed debugging logs, add the --debug flag. This will write verbose logs to ~/.mcp-auth/{server_hash}_debug.log with timestamps and detailed information about the auth process, connections, and token refreshing.

      "args": [
        "mcp-wassenger",
        "API_KEY_GOES_HERE",
        "--debug"
      ]

Claude Desktop

Official Docs

In order to add an MCP server to Claude Desktop you need to edit the configuration file located at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

If it does not exist yet, you may need to enable it under Settings > Developer.

Restart Claude Desktop to pick up the changes in the configuration file. Upon restarting, you should see a hammer icon in the bottom right corner of the input box.

VS Code Extension / Copilot

Official Docs. Add MCP servers through VS Code settings or via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) by searching for "MCP". Configuration is managed through VS Code's settings interface.

Cursor

Official Docs. The configuration file is located at ~/.cursor/mcp.json.

As of version 0.48.0, Cursor supports unauthed SSE servers directly. If your MCP server is using the official MCP OAuth authorization protocol, you still need to add a "command" server and call mcp-wassenger.

Windsurf

Official Docs. The configuration file is located at ~/.codeium/windsurf/mcp_config.json.

Cline

Official Docs. The configuration file is located at ~/.cline/mcp_servers.json.

Continue.dev

Official Docs. The configuration file is located at ~/.continue/config.json. Continue.dev supports MCP servers for enhanced code context and AI-powered development workflows.

Zed Editor

Official Docs. Configure MCP servers in Zed's settings to extend the AI assistant capabilities. Zed provides native MCP integration for seamless development experience.

Jan AI

Official Docs. Jan AI supports MCP servers through its extension system, allowing you to integrate external tools and data sources with local AI models.

Open WebUI

Official MCP Integration. Open WebUI provides MCP support for connecting external tools and services to your self-hosted AI interface, enabling powerful workflow automation.

Sourcegraph Cody

Official Docs. Cody supports MCP integration for enhanced code understanding and AI-assisted development across your entire codebase.

OpenAI Responses API

You can use the Wassenger MCP server as a tool with OpenAI's new Responses API, which provides native MCP integration without requiring manual client setup.

JavaScript Example

import OpenAI from 'openai';

const wassengerKey = process.env.WASSENGER_API_KEY || 'your-wassenger-api-key';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// Send a WhatsApp message using OpenAI's Responses API with MCP
const response = await openai.responses.create({
  model: 'o1-mini',
  tools: [
    {
      type: 'mcp',
      server_label: 'wassenger',
      server_url: `https://api.wassenger.com/mcp?key=${wassengerKey}`,
      require_approval: 'never'
    }
  ],
  input: 'Send a WhatsApp message to +1234567890 saying "Hello from AI!"'
});

console.log('Response:', response);

Python Example

import os
from openai import OpenAI

wassenger_key = os.getenv('WASSENGER_API_KEY', 'your-wassenger-api-key')

client = OpenAI(
    api_key=os.getenv('OPENAI_API_KEY')
)

# Send a WhatsApp message using OpenAI's Responses API with MCP
response = client.responses.create(
    model='o1-mini',
    tools=[
        {
            'type': 'mcp',
            'server_label': 'wassenger',
            'server_url': f'https://api.wassenger.com/mcp?key={wassenger_key}',
            'require_approval': 'never'
        }
    ],
    input='Send a WhatsApp message to +1234567890 saying "Hello from AI!"'
)

print('Response:', response)

Installation

Make sure to install the required dependencies:

JavaScript:

npm install openai

Python:

pip install openai

Environment Variables

Set your API keys as environment variables:

export OPENAI_API_KEY="your-openai-api-key"
export WASSENGER_API_KEY="your-wassenger-api-key"

This approach uses OpenAI's native MCP integration, which automatically handles tool discovery, execution, and communication with the Wassenger MCP server without requiring manual MCP client configuration.

Troubleshooting

Clear your `~/.mcp-auth` directory

mcp-wassenger stores all the credential information inside ~/.mcp-auth (or wherever your MCP_REMOTE_CONFIG_DIR points to). If you're having persistent issues, try running:

rm -rf ~/.mcp-auth

Then restarting your MCP client.

Check your Node version

Make sure that the version of Node you have installed is 18 or higher. Claude Desktop will use your system version of Node, even if you have a newer version installed elsewhere.

Restart Claude

When modifying claude_desktop_config.json it can helpful to completely restart Claude

VPN Certs

You may run into issues if you are behind a VPN, you can try setting the NODE_EXTRA_CA_CERTS environment variable to point to the CA certificate file. If using claude_desktop_config.json, this might look like:

{
 "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-wassenger",
        "API_KEY_GOES_HERE"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "{your CA certificate file path}.pem"
      }
    }
  }
}

Check the logs

Follow Claude Desktop logs in real-time
MacOS / Linux:tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
For bash on WSL:tail -n 20 -f "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log"
Powershell: Get-Content "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20

Debugging

Debug Logs

For troubleshooting complex issues, especially with token refreshing or authentication problems, use the --debug flag:

"args": [
  "mcp-wassenger",
  "API_KEY_GOES_HERE",
  "--debug"
]

This creates detailed logs in ~/.mcp-auth/{server_hash}_debug.log with timestamps and complete information about every step of the connection and authentication process. When you find issues with token refreshing, laptop sleep/resume issues, or auth problems, provide these logs when seeking support.

Authentication Errors

If you encounter the following error, returned by the /callback URL:

Authentication Error
Token exchange failed: HTTP 400

You can run rm -rf ~/.mcp-auth to clear any locally stored state and tokens.

"Client" mode

Run the following on the command line (not from an MCP server):

npx -p mcp-wassenger@latest mcp-wassenger-client API_KEY_GOES_HERE

This will run through the entire authorization flow and attempt to list the tools & resources at the remote URL. Try this after running rm -rf ~/.mcp-auth to see if stale credentials are your problem, otherwise hopefully the issue will be more obvious in these logs than those in your MCP client.

License

MIT

Server	Summary	Actions
Sendblue	An MCP (Model Context Protocol) server that exposes Sendblue's iMessage and SMS capabilities as tool...	View
Twist MCP Server	An MCP server for interacting with a Twist workspace. Written in Python using the Twist REST API. Cu...	View
MCP IDE Bridge		View
any-chat-completions-mcp	Integrate Claude with Any OpenAI SDK Compatible Chat Completion API - OpenAI, Perplexity, Groq, xAI,...	View
Postmark	An MCP server implementation for Postmark email services.	View
DingTalk	钉钉的 Model Context Protocol (MCP) 服务器实现，使 Claude 能够与钉钉工作空间进行交互。	View

Wassenger

MCP Wassenger WhatsApp API Connector

Contents

About

Example prompts

📱 Basic Messaging & Communication

📊 Conversation Analysis & Insights

👥 Group & Team Management

⏰ Message Scheduling & Automation

🔍 Contact & Device Management

📈 Analytics & Reporting

🔔 Status & Monitoring

🔄 Bulk Operations & Campaigns

🎯 Smart Business Automation

🔐 Account & File Management

HTTP streaming usage

Supported Clients

Claude Desktop Configuration

VS Code Copilot Configuration

Benefits of HTTP Streaming

Getting Your API Key

MCP Tools Supported

📱 Core Messaging & Communication

💬 Chat & Conversation Management

👥 Group & Team Management

📺 Channel & Broadcasting

🔄 Campaign & Bulk Operations

📱 Device & Account Management

👤 Contact & Label Management

📁 File & Media Management

🔧 System & Utilities

📊 Analytics & Insights

Usage

Custom Headers

Usage as a tool in OpenAI

Flags

Claude Desktop

VS Code Extension / Copilot

Cursor

Windsurf

Cline

Continue.dev

Zed Editor

Jan AI

Open WebUI

Sourcegraph Cody

OpenAI Responses API

JavaScript Example

Python Example

Installation

Environment Variables

Troubleshooting

Clear your ~/.mcp-auth directory

Check your Node version

Restart Claude

VPN Certs

Check the logs

Debugging

Debug Logs

Authentication Errors

"Client" mode

License

Related in Communication - Secure MCP Servers

Clear your `~/.mcp-auth` directory