@codespar/mcp-z-api

@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.

Links

• Z-API Website
• Z-API Developer Documentation
• MCP Dev Brasil
• Landing Page

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