MCP WaliChat 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 integrate WaliChat 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.
⚠️ 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.
Contents
- About
- Example prompts
- HTTP streaming usage
- MCP Tools Supported
- Usage
- Troubleshooting
- Debugging
- License
About
WaliChat 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 WaliChat 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 WaliChat 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 WaliChat?"
- "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 WaliChat 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 WaliChat 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 WaliChat 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": {
"walichat": {
"type": "http",
"url": "https://api.wali.chat/mcp?key=YOUR_WALICHAT_API_KEY"
}
}
}
Or using environment variables:
{
"mcpServers": {
"walichat": {
"type": "http",
"url": "https://api.wali.chat/mcp?key=${WALICHAT_API_KEY}",
"env": {
"WALICHAT_API_KEY": "your-api-key-here"
}
}
}
}
VS Code Copilot Configuration
In VS Code settings (JSON format):
{
"mcp.servers": {
"walichat": {
"url": "https://api.wali.chat/mcp?key=YOUR_WALICHAT_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 WaliChat.com
- Go to your API settings
- Copy your API key
- Replace
YOUR_WALICHAT_API_KEYin the configuration above
MCP Tools Supported
The WaliChat 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 messagingmanage_whatsapp_message_interactions- Message interactions: reply, forward, reaction, and poll votingget_whatsapp_chat_messages- Comprehensive message retrieval: recent, search, date range, by sender, by type, by ID, advanced search, thread context, and media filteringanalyze_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 filteringanalyze_whatsapp_chats- Chat analytics and export with comprehensive statistics and data export capabilitiessearch_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 typesmanage_whatsapp_group_participants- Participant management: add, remove, promote, demote, approval workflow with 7 action typesmanage_whatsapp_team- Team member management: search, create, update, delete, device access control with 7 action typesmanage_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 typesmanage_whatsapp_channel_messages- Channel message retrieval with filtering and paginationmanage_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 typesmanage_whatsapp_campaign_contacts- Campaign recipient management: search, add, remove contacts with filtering optionsmanage_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 filteringget_whatsapp_device_details- Detailed device information: configuration, session status, metrics, and insightshealth_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 typesmanage_whatsapp_contact_actions- Contact blocking: block and unblock operationsmanage_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 metadatasearch_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-walichat",
"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-walichat",
"${WALICHAT_API}"
],
"env": {
"WALICHAT_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-walichat",
"${WALICHAT_API}"
],
"env": {
"WALICHAT_API": "<walichat-api-get-here>"
}
},
Usage as a tool in OpenAI
Here's how you can use the WaliChat MCP server as a tool with the OpenAI JavaScript client:
import OpenAI from 'openai';
const walichatKey = process.env.WALICHAT_API_KEY || 'walichat-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: 'walichat',
server_url: `https://api.wali.chat/mcp?key=${walichatKey}`,
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 WALICHAT_API_KEY="your-walichat-api-key"
This approach uses OpenAI's new Responses API with MCP integration, which automatically handles tool discovery, execution, and communication with the WaliChat MCP server without requiring manual MCP client setup.
Flags
- If
npxis producing errors, consider adding-yas the first argument to auto-accept the installation of themcp-walichatpackage.
"command": "npx",
"args": [
"-y"
"mcp-walichat",
"API_KEY_GOES_HERE"
]
- To force
npxto always check for an updated version ofmcp-walichat, add the@latestflag:
"args": [
"mcp-walichat@latest"
]
- To change which port
mcp-walichatlistens for an OAuth redirect (by default3334), 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-walichat",
"API_KEY_GOES_HERE"
]
- To enable detailed debugging logs, add the
--debugflag. This will write verbose logs to~/.mcp-auth/{server_hash}_debug.logwith timestamps and detailed information about the auth process, connections, and token refreshing.
"args": [
"mcp-walichat",
"API_KEY_GOES_HERE",
"--debug"
]
Claude Desktop
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-walichat.
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 WaliChat 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 walichatKey = process.env.WALICHAT_API_KEY || 'your-walichat-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: 'walichat',
server_url: `https://api.wali.chat/mcp?key=${walichatKey}`,
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
walichat_key = os.getenv('WALICHAT_API_KEY', 'your-walichat-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': 'walichat',
'server_url': f'https://api.wali.chat/mcp?key={walichat_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 WALICHAT_API_KEY="your-walichat-api-key"
This approach uses OpenAI's native MCP integration, which automatically handles tool discovery, execution, and communication with the WaliChat MCP server without requiring manual MCP client configuration.
Troubleshooting
Clear your ~/.mcp-auth directory
mcp-walichat 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-walichat",
"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-walichat",
"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-walichat@latest mcp-walichat-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