mcp-z-api

Name: mcp-z-api
Author: codespar

Local

github.com/codesparCommunication275Updated 4w ago

Repository

About mcp-z-api

mcp-z-api is an MCP server for Z-API, a WhatsApp messaging platform. It covers sending several message types and managing contacts, chats, groups and labels. It suits AI agents and workflows that communicate with customers over WhatsApp.

Key features

01Send text, image, document, audio and location messages
02Manage contacts, chats and read status
03Create groups and manage participants
04Assign labels to chats
05Send button and option list messages

Use cases

01Automate replies to customer WhatsApp messages from an agent
02Maintain group membership and labels at scale

MCP support

The server exposes Z-API WhatsApp functions as 27 MCP tools that MCP clients can call.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config

{
  "mcpServers": {
    "codespar-mcp-z-api": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-z-api"
      ],
      "env": {
        "ZAPI_TOKEN": "<ZAPI_TOKEN>"
      }
    }
  }
}

Run commandnpx -y @codespar/mcp-z-api

Environment variables to set

ZAPI_TOKENSecretAPI key for z-api

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages

npm@codespar/mcp-z-api0.2.2stdio

Tools

Saved tool list · updated 2w ago

Parameter	Type	Required	Description
phone	string	Yes	Phone number with country code (e.g. 5511999999999)
message	string	Yes	Text message content

Details

From the project README

@codespar/mcp-z-api

MCP server for Z-API — WhatsApp messaging platform

Quick Start

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "z-api": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-z-api"],
      "env": {
        "ZAPI_INSTANCE_ID": "your-instance-id",
        "ZAPI_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

claude mcp add z-api -- npx @codespar/mcp-z-api

Cursor / VS Code

Add to .cursor/mcp.json or .vscode/mcp.json:

{
  "servers": {
    "z-api": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-z-api"],
      "env": {
        "ZAPI_INSTANCE_ID": "your-instance-id",
        "ZAPI_TOKEN": "your-token"
      }
    }
  }
}

Tools (27)

Tool	Purpose
`send_text`	Send a text message via WhatsApp
`send_image`	Send an image message via WhatsApp
`send_document`	Send a document via WhatsApp
`send_audio`	Send an audio message via WhatsApp
`get_contacts`	Get all WhatsApp contacts
`check_number`	Check if a phone number has WhatsApp
`get_profile_picture`	Get profile picture URL for a phone number
`get_messages`	Get messages for a phone number
`send_button_list`	Send a button list message via WhatsApp
`get_status`	Get WhatsApp instance connection status
`create_group`	Create a WhatsApp group
`get_group_metadata`	Get group metadata and participants
`add_group_participant`	Add a participant to a WhatsApp group
`remove_group_participant`	Remove a participant from a WhatsApp group
`send_location`	Send a location message via WhatsApp
`send_contact`	Send a contact card via WhatsApp
`add_label`	Assign a label/tag to a chat
`get_labels`	List all available labels/tags
`read_message`	Mark messages as read
`delete_message`	Delete a message
`get_contact_metadata`	Get metadata (name, WhatsApp display name, profile picture, status) for a single contact
`add_contacts`	Add one or more contacts to the WhatsApp address book.
`list_chats`	List all WhatsApp chats with pagination
`mark_chat_as_read`	Mark an entire chat as read or unread
`list_groups`	List all WhatsApp groups with pagination
`send_option_list`	Send an interactive option list (WhatsApp native list).
`send_button_actions`	Send interactive action buttons (CALL, URL, REPLY).

Authentication

Z-API uses instance ID and token embedded in the request URL.

Sandbox / Testing

Z-API offers a free trial for testing. Create an account to get started.

Get your credentials

Go to Z-API Developer Portal
Create an account and start a free trial
Get your instance ID and token
Set the environment variables

Environment Variables

Variable	Required	Description
`ZAPI_INSTANCE_ID`	Yes	Z-API instance ID
`ZAPI_TOKEN`	Yes	Z-API instance token

Roadmap

v0.2 (planned)

send_sticker — Send a sticker message via WhatsApp
send_reaction — Send a reaction to a message
get_chat_history — Get full chat history with a contact
update_group_settings — Update group name, description, settings
leave_group — Leave a WhatsApp group

v0.3 (planned)

bulk_messaging — Send messages to multiple contacts
template_management — Create and manage message templates
catalog_products — Manage WhatsApp Business catalog products

Want to contribute? Open a PR or request a tool.

Enterprise

Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

Read the getting-started guide

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.