Official MCP server for WapiSender. Use it from Claude Code, Codex, and other MCP-compatible clients to manage WhatsApp instances, send messages, manage contacts, configure webhooks, and build flows.
What This MCP Does
WapiSender MCP gives your MCP client access to the WapiSender platform through a stateful session.
Official MCP server for WapiSender — send WhatsApp messages, manage flows, contacts, and instances from MCP-compatible clients.
2026-11-16
星數
—
工具
—
可用率
—
It supports:
Logging into your WapiSender account with an MCP token
Updated interactive button payloads to use reply buttons shaped as type, displayText, and id.
Updated list rows to use rowId and list footers to use footerText.
Corrected the current reaction, poll, contact-card, audio, media, and location payload contracts.
Message tools now distinguish API acceptance from recipient-visible delivery.
Flows
Added current message_received and manual trigger types.
Added the current webhook and human-handoff node definitions.
Added atomic full-flow creation and cloning.
Added race-safe single-node updates through the dedicated node route.
Added simulate_flow and get_flow_logs for testing and execution inspection.
Contacts, instances, and webhooks
Added live instance refresh through ?live=true.
Added client-side contact search and pagination over WapiSender's normalized contact response.
Replaced the unsupported contact upsert with set_contact_block_status.
Corrected webhook updates to send the nested { webhook: ... } contract.
AI providers and self-hosting
Added Ollama, Mistral, DeepSeek, Groq, Kimi, and Hugging Face alongside the existing providers.
Added credential updates for API-key rotation, base URLs, models, labels, and active state.
Added WAPISENDER_BASE_URL for self-hosted WapiSender deployments.
Compatibility cleanup
Removed MCP tools for application routes that do not currently exist: QR retrieval, disconnect, number checking, chat history, mark-as-read, and contact deletion.
Added 30-second API request timeouts and clearer HTTP error handling.
Replaced duplicated test-only schemas with contract tests against the actual registered tools and emitted payloads.
login to wapisender
list my instances
switch to instance WABZ3
show me the current instance status
send a WhatsApp message to +5491112345678 saying "Hello from WapiSender MCP"
list my flows
create a support flow that asks whether the user needs sales or billing help
Tool-call examples for the same session:
login
{}
switch_instance
{
"instanceIdOrName": "WABZ3"
}
send_text
{
"to": "5491112345678",
"message": "Hello from WapiSender MCP"
}
How Authentication Works
The CLI stores only your MCP token locally. The MCP server loads that token and creates an in-memory session when you call login.
The session tracks:
Your WapiSender account
The list of instances available to that account
The active instance used by all instance-scoped tools
If your account has exactly one instance, it is auto-selected during login.
If your account has more than one instance, you should call:
list_instances
switch_instance
After that, all instance-scoped tools use the selected instance.
Multiple Instances
Yes, multi-instance accounts are supported.
Typical workflow
Log in
List your instances
Pick the instance you want to work on
Switch to it
Run your messaging, flow, webhook, or contact tools
Example:
login to wapisender
list my instances
switch to instance Sales-BR
send a message to 5491112345678 saying "Hello from the Brazil sales number"
Tool-call example:
list_instances
{}
switch_instance
{
"instanceIdOrName": "Sales-BR"
}
Expected behavior:
login auto-selects the instance if the account has only one
switch_instance accepts either the instance name or the instance ID
All subsequent tool calls use the new active instance
There are 42 tools grouped into 7 areas. The catalog is generated from routes that currently exist in WapiSender; unsupported chat-history, contact-delete, QR, disconnect, and number-check routes are intentionally not exposed.
Auth
login
Loads saved credentials and connects to your WapiSender account.
Notes:
No arguments
Auto-selects the active instance if your account has only one instance
Example:
{}
logout
Clears the current WapiSender session.
Example:
{}
list_instances
Lists all WhatsApp instances on your WapiSender account.
Example:
{}
switch_instance
Sets the active instance by ID or by instance_name.
Example:
{
"instanceIdOrName": "WABZ3"
}
refresh_instances
Re-fetches the instance list from the API and updates the session — without requiring a full re-login. Useful after adding a new instance.
Example:
{}
get_session_info
Returns the current session state: who you are logged in as, all instances, and which instance is active. Makes no API calls — reads local session only.
Example:
{}
Instance
get_instance_status
Returns the connection state for the active instance, including phone number and battery level when available.
Example:
{}
Messaging
send_text
Submits a text WhatsApp message. API acceptance does not prove recipient delivery.
Example:
{
"to": "5491112345678",
"message": "Hello from WapiSender MCP"
}
send_media
Sends an image, video, or document from a public URL. caption is optional and omitted when not provided.
{
"flowId": "a07692d5-a56c-4027-9cb9-19b44c33eb2c",
"nodeId": "message-1",
"data": {
"text": "Hello. Reply with sales, support, or billing."
}
}
generate_and_save_flow
Generates a complete WhatsApp flow from a plain-English description and saves it fully in one step — including the node graph. The AI generates the nodes and edges, then this tool creates and saves everything atomically.
Example:
{
"name": "Lead Qualification",
"description": "A flow that greets the user, asks for their company size, and routes enterprise leads to sales.",
"triggerType": "message_received",
"triggerConfig": {},
"nodes": [ ... ],
"edges": [ ... ]
}
Natural-language example:
Generate and save a WhatsApp flow named "Lead Qualification" that greets the user, asks for company size, and routes enterprise leads to sales.
rename_flow
Renames an existing flow without touching its node graph or activation state.
Example:
{
"flowId": "a07692d5-a56c-4027-9cb9-19b44c33eb2c",
"name": "New Flow Name"
}
Returns the current webhook configuration for the active instance.
Example:
{}
set_webhook
Creates or updates the webhook URL and event subscriptions. The events array accepts only known event types:
MESSAGES_UPSERT — new message received or sent
MESSAGES_UPDATE — message status update
MESSAGE_RECEIPT_UPDATE — delivery/read receipt updates
CONNECTION_UPDATE — connection state changes
QRCODE_UPDATED — new QR code available
CONTACTS_UPSERT — contact added or updated
CONTACTS_UPDATE — contact updated
PRESENCE_UPDATE — user presence changes
CHATS_UPSERT — chat metadata updates
GROUPS_UPSERT — group created or updated
GROUP_PARTICIPANTS_UPDATE — group participant changes
Example 3: Create and activate a simple support flow
login to wapisender
switch to instance Support-Number
create a flow named "Support Router"
update that flow so it greets the user and asks whether they need sales or support
activate the flow
Example 4: Add and test an AI credential
login to wapisender
switch to instance Demo-Instance
add an OpenAI credential labeled "OpenAI Production" using model gpt-4o-mini
list my AI credentials
test the credential I just added
Common Usage Patterns
Pattern: Start every session cleanly
login to wapisender
list my instances
switch to instance <name>
get the instance status
Pattern: Work with multiple instances safely
list my instances
switch to instance Sales-AR
send a message to 5491112345678 saying "Sales team checking in"
switch to instance Support-AR
send a message to 5491112345678 saying "Support team following up"
Pattern: Build a flow incrementally
create a flow named "Lead Capture"
get the flow details
update a single node
activate the flow
Troubleshooting
Not authenticated or Not logged in
Save credentials first:
npx wapisender-mcp login --token <your-mcp-token>
Then call login again inside your MCP client.
No active instance. Call switch_instance() or login() first.
Your account probably has multiple instances and none is selected yet.
Run:
list my instances
switch to instance <instance name or id>
Instance "<name>" not found in your account.
Use list_instances first and copy the exact instance name or ID.
Invalid token or network error
Check:
The token was copied correctly
The token is still valid in WapiSender
The client machine can reach wapisender.com
Security Notes
The CLI stores your MCP token locally in ~/.config/wapisender-mcp/credentials.json
AI provider API keys passed through add_ai_credential are encrypted server-side by WapiSender
The MCP server keeps active session state in memory while it is running
Package Metadata
This repository publishes the npm package:
wapisender-mcp
The top-level README.md is the package README used by npm and by MCP clients that display package documentation, so keeping this file current keeps the Codex-facing package docs current as well.