mcpField
M
mcp-z-api

mcp-z-api

本地服务
github.com/codespar通信协作2754 周前更新
代码仓库

关于 mcp-z-api

mcp-z-api 是 Z-API WhatsApp 消息平台的 MCP 服务，可发送多种类型消息并管理联系人、群组与标签。适合需要通过 WhatsApp 与客户沟通的 AI Agent 与工作流。

主要功能

  1. 01发送文本、图片、文档、音频与位置消息
  2. 02管理联系人、聊天与已读状态
  3. 03创建群组并管理成员
  4. 04为聊天添加标签
  5. 05发送按钮与选项列表等交互消息

适用场景

  1. 01通过 AI Agent 自动回复客户 WhatsApp 消息
  2. 02批量维护 WhatsApp 群组成员与标签

MCP 相关

该服务将 Z-API 的 WhatsApp 功能以 27 个 MCP 工具形式暴露，供 MCP 客户端调用。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "codespar-mcp-z-api": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-z-api"
      ],
      "env": {
        "ZAPI_TOKEN": "<ZAPI_TOKEN>"
      }
    }
  }
}
启动命令npx -y @codespar/mcp-z-api
需要配置的环境变量
ZAPI_TOKEN密钥API key for z-api

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npm@codespar/mcp-z-api0.2.2

工具

27

收录的工具列表 · 更新于 2 周前

参数类型必填说明
phonestring是带国家/地区代码的电话号码（例如 5511999999999）
messagestring是文本消息内容

详细介绍

@codespar/mcp-z-api

面向 Z-API 的 MCP 服务 — WhatsApp 消息平台

npm License: MIT

快速开始

Claude Desktop

添加到 ~/.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

添加到 .cursor/mcp.json 或 .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"
      }
    }
  }
}

工具（27 个）

工具用途
send_text通过 WhatsApp 发送文本消息
send_image通过 WhatsApp 发送图片消息
send_document通过 WhatsApp 发送文档
send_audio通过 WhatsApp 发送音频消息
get_contacts获取所有 WhatsApp 联系人
check_number检查电话号码是否已注册 WhatsApp
get_profile_picture获取电话号码对应的头像 URL
get_messages获取电话号码对应的消息
send_button_list通过 WhatsApp 发送按钮列表消息
get_status获取 WhatsApp 实例的连接状态
create_group创建 WhatsApp 群组
get_group_metadata获取群组元数据和参与者
add_group_participant将参与者添加到 WhatsApp 群组
remove_group_participant从 WhatsApp 群组中移除参与者
send_location通过 WhatsApp 发送位置消息
send_contact通过 WhatsApp 发送联系人名片
add_label为聊天分配标签
get_labels列出所有可用标签
read_message将消息标记为已读
delete_message删除消息
get_contact_metadata获取单个联系人的元数据（姓名、WhatsApp 显示名称、头像、状态）
add_contacts将一个或多个联系人添加到 WhatsApp 通讯录。
list_chats分页列出所有 WhatsApp 聊天
mark_chat_as_read将整个聊天标记为已读或未读
list_groups分页列出所有 WhatsApp 群组
send_option_list发送交互式选项列表（WhatsApp 原生列表）。
send_button_actions发送交互式操作按钮（CALL、URL、REPLY）。

身份验证

Z-API 使用嵌入在请求 URL 中的实例 ID 和令牌。

沙盒 / 测试

Z-API 提供免费试用以供测试。创建账户即可开始使用。

获取凭据
  1. 前往 Z-API 开发者门户
  2. 创建账户并开始免费试用
  3. 获取实例 ID 和令牌
  4. 设置环境变量

环境变量

变量必填描述
ZAPI_INSTANCE_ID是Z-API 实例 ID
ZAPI_TOKEN是Z-API 实例令牌

路线图

v0.2（计划中）
  • send_sticker — 通过 WhatsApp 发送贴纸消息
  • send_reaction — 对消息发送回应
  • get_chat_history — 获取与联系人的完整聊天记录
  • update_group_settings — 更新群组名称、描述和设置
  • leave_group — 退出 WhatsApp 群组
v0.3（计划中）
  • bulk_messaging — 向多个联系人发送消息
  • template_management — 创建和管理消息模板
  • catalog_products — 管理 WhatsApp Business 商品目录

想要贡献？提交 PR 或申请工具。

链接

企业版

需要为 Agent 付款设置治理、预算限额和审计追踪？CodeSpar Enterprise 在这些 MCP 服务之上提供策略引擎、付款路由和合规模板。

许可证

MIT

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。