MCP (Model Context Protocol)

Connect your AI tools to Whapi using MCP

Connect your AI agent — Cursor, Claude Code, Claude Desktop, GitHub Copilot — directly to WhatsApp. With the Whapi MCP server your agent can send messages, manage groups, post to channels, and check channel status by calling real API methods, instead of guessing what the requests should look like.

You don't need to be a developer. With MCP connected, you can simply ask your agent to send a message, create a group, or check channel status — it calls the real API and does it. No code involved. And if you are building something, the agent can test against the live API as it goes, instead of guessing what requests should look like. Pair it with the Agent Skill so the code it writes is correct too.

The Model Context Protocol itself is an open standard for giving AI agents structured access to tools and APIs through one unified interface.

---

Before you start

You need:

• A Whapi.Cloud channel with a WhatsApp number already paired — panel.whapi.cloud

• Your channel token, copied from the channel page

• Node.js 18 or newer

Use the channel token, not a Partner Token. The MCP server connects to one specific channel and works with that channel's credentials. The token appears on the channel page only after a WhatsApp number has been paired.

Quick start

Run the server with your token:

# macOS / Linux
API_TOKEN="YOUR_TOKEN" npx -y whapi-mcp@latest

# Windows PowerShell
$env:API_TOKEN="YOUR_TOKEN"; npx -y whapi-mcp@latest

In practice you rarely run this by hand — your MCP client starts it for you (see below).

whapi-mcp is self-hosted. It runs as a local process on your own machine, launched by your MCP client over stdio. There is no hosted endpoint and no remote URL to connect to — the package has no HTTP or SSE transport. Your channel token never leaves your machine, and the server runs only while your agent is running.

Any environment with Node.js 18+ works — laptop, VM, or a container next to your app — as long as the agent runs there too.

Connect your agent

Add the server to your client's MCP config, then restart the client.

Cursor — %USERPROFILE%\.cursor\mcp.json (Windows) or ~/.cursor/mcp.json (macOS/Linux):

{
  "mcpServers": {
    "whapi-mcp": {
      "command": "npx",
      "args": ["-y", "whapi-mcp@latest"],
      "env": { "API_TOKEN": "YOUR_TOKEN" }
    }
  }
}

Claude Desktop — %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS). Same structure.

Claude Code, VS Code and other MCP clients use the same mcpServers block — only the file location differs.

Verify the connection

Ask your agent to call checkHealth with no arguments. The status.text field tells you where the channel stands:

Status	Meaning	What to do
AUTH	Connected and operational	Ready to use
QR	Waiting for QR scan	Open the channel dashboard and scan
INIT	Server initializing	Wait 40–50 seconds
LAUNCH	Connecting to WhatsApp	Wait a few seconds
STOP	Channel deactivated	Check your subscription
SYNC_ERROR	Sync failure	Log the channel out and reconnect

A 404 Channel not found means the token is wrong, or no number is paired with the channel yet.

Tools

The server exposes 165 tools generated from the Whapi OpenAPI spec — messaging, groups, channels, communities, contacts, labels, media, and channel settings. Each tool maps to one API method.

Sending a text message:

name: sendMessageText
arguments: {
  "to": "[e-mail]",
  "body": "Hello"
}

Chat ID format matters, and getting it wrong is the single most common mistake:

• Personal chat — <phone_number>@s.whatsapp.net (digits only, no +)

• Group — <group_id>@g.us

• WhatsApp Channel (Newsletter) — <newsletter_id>@newsletter

If your model struggles with 165 tools

Some LLMs slow down or refuse to load an MCP server that exposes a large tool list. whapi-mcp-optimal is a slim build with a curated core toolset:

{
  "mcpServers": {
    "whapi-mcp": {
      "command": "npx",
      "args": ["-y", "whapi-mcp-optimal@latest"],
      "env": { "API_TOKEN": "YOUR_TOKEN" }
    }
  }
}

Use whapi-mcp@latest for the full feature set, and whapi-mcp-optimal@latest when tool discovery is slow or the model won't start.

---

Install the Agent Skill too

The MCP server gives your agent access. The Whapi Agent Skill gives it the rules — correct Chat ID formats, real parameter names, webhooks instead of polling. Install for every detected agent at once:

npx skills add Whapi-Cloud/whapi-whatsapp-api-skill

Learn more →

---

Frequently asked

Can I use this if I don't know how to code? Yes. You can use MCP without writing anything at all — just ask your agent to send messages or manage groups, and it does it through the API. And if you're vibe coding a real integration, MCP lets the agent verify each call against the live API instead of guessing. Install the Agent Skill alongside it so the code it writes follows the actual API rules.

Is there a hosted MCP server or a URL I can connect to? No. whapi-mcp is self-hosted and runs locally over stdio. There is no remote endpoint.

Which token goes in API_TOKEN? The channel token from your channel page. Not a Partner Token.

Do I need a paid channel? You can start on the free trial channel — the full API is available, within the trial limits.

Which agents are supported? Any MCP-compatible client: Cursor, Claude Code, Claude Desktop, VS Code, GitHub Copilot, Codex and others.