This MCP server lets you send and manage WhatsApp messages, inspect connected phone numbers, and retrieve account information via Chatmaid's API — usable from AI clients like Claude, Cursor, and Windsurf.
Messaging:
Send WhatsApp messages — Send text and/or media to any E.164 number from a connected phone, with an optional idempotency key to prevent duplicates
List sent messages — Paginate through outbound messages, filterable by status (pending, sent, failed) or sender phone number
Get a specific message — Fetch full details including delivery status and timestamps
Inbound Messages:
List received messages — View messages received by your phone numbers (live environment only), with pagination and filtering
Get a specific inbound message — Fetch details of a received message by ID
Phone Number Management:
List phone numbers — View all numbers registered to your account
Get phone number details — Retrieve details by internal ID or E.164 format
Check connection status — Verify whether a number is currently connected to WhatsApp and ready to send
Account & Usage:
Get account info — Retrieve profile details including name, email, and subscription status
Get usage stats — View message and API request counts for a chosen period (day, week, or month)
Allows sending WhatsApp messages, listing messages, fetching message details, managing phone numbers, and checking account usage via the Chatmaid WhatsApp Developers API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@chatmaid/mcp Send a WhatsApp message to +14155551234 saying the order has shipped."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for the Chatmaid WhatsApp Developers API. Send WhatsApp messages and manage your account from Claude Code, Cursor, Windsurf, Claude Desktop, and any other MCP-compatible AI client.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"chatmaid": {
"command": "npx",
"args": ["-y", "@chatmaid/mcp"],
"env": {
"CHATMAID_API_KEY": "sk_test_xxx_or_sk_live_xxx"
}
}
}
}Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"chatmaid": {
"command": "npx",
"args": ["-y", "@chatmaid/mcp"],
"env": { "CHATMAID_API_KEY": "sk_test_xxx_or_sk_live_xxx" }
}
}
}claude mcp add chatmaid \
--env CHATMAID_API_KEY=sk_test_xxx \
-- npx -y @chatmaid/mcpRelated MCP server: WAHA MCP
Variable | Required | Description |
| Yes | Your API key. Use |
| No | Override the API base URL. Defaults to |
Get a key at https://developers.chatmaid.net/dashboard/api-keys.
Tool | Description |
| Send a WhatsApp message: |
| List the WhatsApp groups a connected phone can post to; returned |
| List recent messages, optionally filtered by |
| Fetch a message by ID, including final status and timestamps. |
| List messages received by your connected phone numbers (live only), optionally filtered by |
| Fetch an inbound (received) message by ID ( |
| List phone numbers registered to the account (scoped to your API key environment). |
| Get details for a single phone number. Accepts internal ID or E.164. |
| Check if a phone number is currently connected to WhatsApp. Accepts internal ID or E.164. |
| Get current account info (accountId, name, email, subscription status). |
| Get usage stats for |
Once installed, you can ask your agent things like:
"Send a WhatsApp message from my business number to +14155551234 saying the order has shipped."
"What phone numbers are connected to my Chatmaid account?"
"Check if message msg_abc123 was delivered."
"Show me the latest messages received on my business number."
"How much of my WhatsApp quota have I used this month?"
The agent will call the right tool automatically.
Always use sk_test_* keys when prototyping with agents. Messages sent with test keys are simulated end-to-end through Chatmaid's sandbox — nothing goes out to WhatsApp.
Promote to sk_live_* only when you've confirmed the agent's behavior.
Open-source at github.com/chatmaid/mcp. PRs welcome.
MIT © Chatmaid
Get current account profile (accountId, name, email, subscriptionStatus, aggregate stats).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose whether authentication is needed, what 'aggregate stats' entails, or any side effects. As a getter, it is likely read-only, but this is not stated explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the purpose and key outputs without any redundant information. It is front-loaded and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no parameters and no output schema, but the description lists several returned fields. While it could elaborate on 'aggregate stats', it is largely complete for a simple retrieval tool. The sibling tools are entirely different, so no confusion arises.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and the input schema is empty with 100% coverage. The description adds value by enumerating the returned fields, which is helpful for understanding the output beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('current account profile'), and lists specific fields returned (accountId, name, email, subscriptionStatus, aggregate stats). It is distinct from sibling tools which focus on messages and phone numbers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (to retrieve account profile info), but does not explicitly mention when not to use or reference alternatives. However, the context is sufficiently clear given the sibling tools are about different resources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single message by ID, including final delivery status and timestamps (createdAt, sentAt, failedAt).
| Name | Required | Description | Default |
|---|---|---|---|
| messageId | Yes | The message ID returned from send_message (e.g. msg_abc123). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only describes the return content but does not disclose whether the operation is read-only, any authentication requirements, rate limits, or what happens for invalid IDs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core purpose and includes specific output details. Every word adds value; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (1 param, no output schema). The description mentions return fields (delivery status, timestamps) but does not cover all possible output fields or behavior (e.g., error handling, read-only nature). Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing a baseline of 3. The description adds value by specifying the exact format of the message ID (e.g., 'msg_abc123') and that it comes from send_message, which helps agents understand the parameter's origin.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch', the resource 'a single message by ID', and specifies what is included ('final delivery status and timestamps'). It distinguishes from siblings like list_messages (multiple) and send_message (send).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific message ID to retrieve details, which distinguishes it from list_messages. However, it does not explicitly mention when not to use it or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details about a single registered phone number. Accepts either the internal phone ID or an E.164 number.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Either the phone's internal ID, or its E.164 number (e.g. +14155551234). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavior. It only says 'get details' without explaining what details are returned, error handling, or any side effects. This is insufficient for a tool that might fail with invalid identifiers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the verb and resource. It contains no fluff, though it could be slightly more structured to separate purpose from parameter usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description should explain the return value or behavior in case of invalid input. It does not, leaving the agent with incomplete context for a simple lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the id parameter with a description matching the tool's text. The description adds no new meaning beyond confirming the two identifier formats, which is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets details about a single registered phone number, using a specific verb and resource. It distinguishes itself from siblings like list_phone_numbers by focusing on a single number and specifying two accepted identifier formats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing details of a single number but does not explicitly state when to use this tool versus alternatives like list_phone_numbers or get_phone_status. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether a phone number is currently connected to WhatsApp and ready to send. Accepts either the internal phone ID or an E.164 number.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Either the phone's internal ID, or its E.164 number (e.g. +14155551234). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It discloses that the tool checks connectivity and accepts two ID formats, implying a read-only operation. It does not specify error cases or output details, but for a simple status check, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that immediately conveys the purpose and input requirements. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple status check without an output schema, the description is largely complete. However, it does not specify what the output represents (e.g., boolean, status text), which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% as the parameter 'id' is described with the same information. The description adds no extra meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('check whether'), the resource ('phone number'), and the specific condition ('connected to WhatsApp and ready to send'). It distinguishes itself from sibling tools like get_phone_number (which likely returns details) and send_message (which sends a message).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage before sending a message by checking readiness, providing clear context. However, it does not explicitly state when not to use or mention alternatives, so it lacks some explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get usage stats for the account over a window (day, week, or month). Returns message and API request counters.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | Reporting window. Defaults to month. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions return of counters but lacks details on data freshness or scope (e.g., real-time? inclusive of current period?). Adequate for a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with two clauses, front-loaded verb and resource. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains inputs (period) and outputs (counters) adequately for a simple tool without output schema. Could mention read-only nature explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with full enum description. Description restates 'window (day, week, or month)' without adding new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Get' and resource 'usage stats for the account' with window options. Distinct from sibling tools like get_account or list_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for retrieving account usage stats, but no explicit when-to-use or alternatives compared to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent WhatsApp messages with offset/limit pagination, optionally filtered by status or sender phone number ID. Response includes a pagination block.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Defaults to 1. | |
| limit | No | Items per page. Defaults to 20, max 100. | |
| status | No | Filter by message status. | |
| phoneNumberId | No | Only return messages sent from this phone number ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. Mentions pagination (offset/limit), filters, and response includes a pagination block, but lacks details on sorting, default ordering (recent), and full response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence front-loaded with key action and resource, followed by details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no output schema, and no annotations, the description covers pagination and filters but omits details on the message object fields in the response, which an agent would need to process results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds 'recent' and 'optionally filtered', but does not enrich parameter understanding beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists recent WhatsApp messages with pagination and optional filters. Distinguishes from siblings like get_message (single message) and send_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use for listing multiple messages but does not explicitly contrast with get_message for individual messages or specify when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all phone numbers registered to the current Chatmaid account (scoped to the API key's environment). Returned id values are valid fromPhoneId arguments for send_message.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It discloses the scope (current account and API key environment) and that ids are valid for send_message. It doesn't mention pagination or ordering, but for a simple read operation with no parameters, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of two sentences. The first states purpose and scope, the second adds practical usage. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description provides essential context: it lists phone numbers and ids are reusable. It doesn't mention ordering or maximum results, but for a simple list, this is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so baseline is 4. The description adds context by explaining that returned ids are valid arguments for send_message, which is valuable beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all phone numbers for the current account, scoped to the API key's environment. It also explains the purpose of returned ids, distinguishing it from the get_phone_number sibling by indicating it's a list vs. a single item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly tells when to use it: to get phone numbers for later use with send_message. It doesn't explicitly mention when not to use it or alternatives like get_phone_number for detailed info, but the context is sufficiently clear for a list operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a WhatsApp message via Chatmaid from one of the account's connected phones. Returns the full message resource (id, status, timestamps). Use list_phone_numbers first to find a valid fromPhoneId.
| Name | Required | Description | Default |
|---|---|---|---|
| fromPhoneId | Yes | ID of a phone number registered in your Chatmaid account (use list_phone_numbers to discover IDs). NOT the raw phone number. | |
| to | Yes | Recipient phone number in E.164 format (e.g. +14155559876). | |
| content | No | Text body of the WhatsApp message. Required if mediaUrls is empty. Max 4096 characters. | |
| mediaUrls | No | Public HTTPS URLs of media to attach. Required if content is empty. Combine with content for a captioned media message. | |
| idempotencyKey | No | Optional idempotency key (max 64 chars) so retries return the original message instead of sending a duplicate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. Discloses mutation (sending message), returns full resource, and mentions idempotency. However, lacks details on rate limits, auth requirements, cost implications, or error scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first covers purpose and return, second provides prerequisite. Zero wasted words, efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-param tool with no output schema, description covers purpose, return type, parameter interplay, and prerequisite. Could add more on expected response structure, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value: clarifies fromPhoneId is not raw number, explains content/mediaUrls interplay, max length, idempotency key. Goes beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it sends a WhatsApp message via Chatmaid from connected phones. Specifies the action, medium, and returns full message resource with id, status, timestamps. Distinguishes from sibling tools like get_message, list_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use list_phone_numbers first to get a valid fromPhoneId. Provides clear context for tool use, though does not explicitly state when not to use it or mention alternatives beyond the prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_accountget_messageget_phone_numberget_phone_statusget_usagelist_messageslist_phone_numberssend_messageScored across 8 tools
Each tool targets a distinct resource and action: account, usage, single message, message list, phone number details, phone status, phone number list, and sending messages. No overlap in functionality.
All tool names follow a consistent verb_noun pattern with snake_case: get_*, list_*, send_message. Verbs are uniformly chosen (get, list, send).
With 8 tools, the surface is well-scoped for a WhatsApp messaging API, covering account management, phone number operations, message retrieval, and sending. Neither too sparse nor excessive.
Covers core operations for the domain: account info, usage, phone number details and status, message listing with filtering, phone number listing, and sending. Minor gap in update/delete operations, but these are often limited by WhatsApp API constraints.
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
Let Claude or ChatGPT search, read and send your WhatsApp messages over MCP. OAuth sign-in.
WhatsMCP connects Claude and other MCP-compatible AI agents directly to WhatsApp. Send and receive text, images, documents, and voice notes; manage groups (create, add/remove members, promote admins); look up contacts and profiles; follow channels; and read call and message history — all through a standard MCP interface. For voice use cases, WhatsMCP offers SIP-based calling plans (inbound-only, or full inbound/outbound) so AI voice agents can answer and place WhatsApp calls, plus low-latency WebSocket integrations with voice agent providers like ElevenLabs. Multiple WhatsApp accounts can be paired and managed per workspace, with webhook support for real-time inbound message delivery to your own infrastructure.
Your own WhatsApp as an MCP server: read, search and send from any MCP client.
