Kaption WhatsApp

@kaptionai/mcp-extension

MCP 服务可让 AI 助手通过 KaptionAI Chrome 扩展读取和管理你的 WhatsApp 对话。还支持 WebMCP，可零配置地发现浏览器原生 AI 工具。

Claude / Cursor ──stdio──> mcp-whatsapp ──ws://localhost:7865──> KaptionAI Extension ──> WhatsApp Web
Browser AI Agent ──navigator.modelContext──> KaptionAI Extension ──> WhatsApp Web (WebMCP)

Agent 技能

教会 Claude Code、Codex、Cursor 和其他 Agent 如何高效使用这些工具（先搜索，发送前务必确认，区分提醒与定时消息，并处理错误）：

npx skills add Kaption-AI/mcp-extension

技能文件位于 skills/kaption-whatsapp/SKILL.md。

设置

1. 安装扩展

安装 KaptionAI Chrome Extension，并在设置中启用 MCP 桥接。

2. 配置你的 AI 工具

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "@kaptionai/mcp-extension@latest"]
    }
  }
}

Claude Code

claude mcp add whatsapp -- npx -y @kaptionai/mcp-extension@latest

Cursor

添加到项目中的 .cursor/mcp.json，或前往 Settings > MCP Servers：

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "@kaptionai/mcp-extension@latest"]
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "@kaptionai/mcp-extension@latest"]
    }
  }
}

VS Code（Copilot）

添加到项目中的 .vscode/mcp.json：

{
  "servers": {
    "whatsapp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kaptionai/mcp-extension@latest"]
    }
  }
}

也可以添加到 VS Code 的 settings.json：

{
  "mcp": {
    "servers": {
      "whatsapp": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@kaptionai/mcp-extension@latest"]
      }
    }
  }
}

Zed

添加到 Zed 设置（~/.config/zed/settings.json）：

{
  "context_servers": {
    "whatsapp": {
      "command": {
        "path": "npx",
        "args": ["-y", "@kaptionai/mcp-extension@latest"]
      }
    }
  }
}

OpenAI Agents SDK（Python）

from agents import Agent
from agents.mcp import MCPServerStdio

whatsapp = MCPServerStdio(
    name="whatsapp",
    command="npx",
    args=["-y", "@kaptionai/mcp-extension@latest"],
)

agent = Agent(
    name="assistant",
    instructions="You can access WhatsApp conversations.",
    mcp_servers=[whatsapp],
)

任何兼容 MCP 的客户端

此软件包通过 stdio 作为标准 MCP 服务运行。要从任何客户端连接：

npx -y @kaptionai/mcp-extension@latest

服务使用 MCP 协议通过 stdin/stdout 通信。将客户端的 MCP 配置指向此命令。

3. 打开 WhatsApp Web

在 Chrome 或 Edge 中打开 web.whatsapp.com。扩展会自动连接到 MCP 服务。

工具

query

查询 WhatsApp 数据 — 对话、联系人、消息、转录文本、标签和社群。

# List conversations
query {}

# Search everything
query { query: "meeting" }

# Unread only
query { unread: true }

# Look up a conversation with messages
query { id: "[email protected]" }

# Search contacts
query { query: "Alice", entity: "contacts" }

# List labels (Business accounts)
query { entity: "labels" }

# Filter by label
query { label: "Important" }

# List communities
query { entity: "communities" }

# Filter by community
query { community: "My Community" }

# Get session info
query { entity: "session" }

参数	类型	描述
query	string	搜索文本（姓名、消息、转录文本）
id	string	查找特定对话、联系人或标签
entity	string	conversations、contacts、messages、transcriptions、labels、communities、session
limit	number	最大结果数（默认值为 25，最大值为 5000）
unread	boolean	仅包含未读对话
label	string	按标签名称或 ID 筛选
community	string	按社群名称或 ID 筛选
before	string	此 ISO 8601 时间戳之前的消息（分页）
after	string	此 ISO 8601 时间戳之后的消息（增量同步）

summarize_conversation

生成对话摘要。

参数	类型	描述
conversation_id	string	对话 ID

manage_labels

管理 WhatsApp Business 标签 — 添加、移除、创建或删除标签。

参数	类型	描述
action	string	add、remove、create、delete
label_name	string	标签名称
label_id	string	标签 ID（可替代名称）
conversation_id	string	添加或移除时必需

manage_lists

管理个人聊天列表（自定义列表）。这是个人账号中 Business 标签的对应功能 — 可将聊天整理到自定义类别中。

# List all custom lists
manage_lists { action: "list" }

# Get a list with its chats
manage_lists { action: "get", name: "Family" }

# Create a new list
manage_lists { action: "create", name: "Work", conversation_id: "[email protected]" }

# Add a chat to a list
manage_lists { action: "add_chat", name: "Family", conversation_id: "[email protected]" }

# Remove a chat from a list
manage_lists { action: "remove_chat", name: "Family", conversation_id: "[email protected]" }

# Delete a list
manage_lists { action: "delete", name: "Old List" }

参数	类型	描述
action	string	list、get、create、edit、delete、add_chat、remove_chat
id	string	列表 ID
name	string	列表名称（用于创建/编辑，或按名称查找）
conversation_id	string	要添加/移除的聊天 ID

manage_chat

管理聊天状态——归档、取消归档、标记为已读/未读、置顶、取消置顶、静音、取消静音、设置/清除草稿消息。

# Archive a chat
manage_chat { action: "archive", conversation_id: "[email protected]" }

# Mark as read
manage_chat { action: "mark_read", conversation_id: "[email protected]" }

# Pin a chat (max 3)
manage_chat { action: "pin", conversation_id: "[email protected]" }

# Mute for 1 week
manage_chat { action: "mute", conversation_id: "[email protected]", mute_duration: "1w" }

# Set a draft message
manage_chat { action: "set_draft", conversation_id: "[email protected]", text: "Hey, I'll call you back" }

参数	类型	描述
action	字符串	archive、unarchive、mark_read、mark_unread、pin、unpin、mute、unmute、set_draft、clear_draft
conversation_id	字符串	会话 ID
mute_duration	字符串	8h、1w 或 forever（默认值）。仅用于 mute
text	字符串	草稿文本。set_draft 必填

manage_reminders

创建和管理个人提醒。提醒存储在云端，并通过 Kaption 扩展送达。

# List active reminders
manage_reminders { action: "list" }

# Create a reminder
manage_reminders { action: "create", title: "Follow up with client", datetime: "2026-03-07T14:00:00Z" }

# Complete a reminder
manage_reminders { action: "complete", id: "rem_abc123" }

# List all including completed
manage_reminders { action: "list", filter: "all" }

参数	类型	描述
action	字符串	list、get、create、update、delete、complete、uncomplete
filter	字符串	用于 list：active（默认值）、completed、all
id	字符串	提醒 ID（用于 get/update/delete/complete/uncomplete）
title	字符串	提醒文本（最多 800 个字符，不含换行符）
datetime	字符串	ISO 8601 日期时间
notification_type	字符串	extension、whatsapp 或 automatic（默认值）

manage_scheduled_messages

安排消息在指定时间自动发送，支持以下两种模式：

• bot（默认值）——通过 Kaption 的 WhatsApp 号码发送，而不是你的号码。消息存储在 Kaption 的云端，即使电脑关机也会发送。仅支持一对一聊天；单行，最多 800 个字符。
• local（“通过此电脑发送”）——通过你自己的 WhatsApp 号码以你的身份发送，前提是此电脑和 WhatsApp 均处于打开状态。消息不会离开你的设备。Kaption 会自动将发送量控制在安全范围内（每小时和每天发送数条消息，消息间隔几分钟；仅发送到对方曾发过消息的聊天；群组每天最多发送 3 条），超出限制的请求会被拒绝并说明原因。只有此模式可以向群组发送消息（仅限你有权发言且最近 30 天内发过消息的群组）。仅支持文本。若电脑关机期间错过了发送时间，该消息会标记为未发送，不会在之后自动补发。

你必须先在 Kaption 中开启本地模式（阅读限制和风险后，在发送计划消息的选择器中选择“通过此电脑发送”）。AI 助手无法替你开启此模式；在你开启之前，本地发送请求会因 (reason: no-consent) 被拒绝。此功能也在逐步推出中：尚未开放的地区会因 (reason: flag-off) 拒绝本地发送请求，bot 模式则照常工作。

# List pending messages of both modes (each one has a "mode")
manage_scheduled_messages { action: "list" }

# Schedule with the Kaption bot
manage_scheduled_messages { action: "create", message: "Hey, just following up!", datetime: "2026-03-07T09:00:00Z", conversation_id: "[email protected]" }

# Schedule from your own number, or to a group
manage_scheduled_messages { action: "create", mode: "local", message: "Running 10 min late", datetime: "2026-03-07T09:00:00-03:00", conversation_id: "[email protected]" }
manage_scheduled_messages { action: "create", mode: "local", message: "Standup moved to 10", datetime: "2026-03-07T09:00:00Z", conversation_id: "[email protected]" }

# Cancel a scheduled message
manage_scheduled_messages { action: "delete", id: "msg_abc123" }
manage_scheduled_messages { action: "cancel", mode: "local", id: "3f2c…" }

参数	类型	描述
action	字符串	list、get、create、update、delete；使用 mode: "local" 时，还支持 cancel、remove（已完成的消息）和 send_now（未发送或发送失败的消息）
mode	字符串	bot（默认值）或 local。用于 list 时，省略此参数可获取两种模式的消息
filter	字符串	用于 list：pending（默认值）、sent、all
id	字符串	计划消息 ID（用于 get/update/delete/cancel/remove/send_now）
conversation_id	字符串	要发送到的聊天（用于 create）：个人聊天，或使用 mode: "local" 时的群组聊天
message	字符串	消息文本。Bot 模式：最多 800 个字符，不含换行符。本地模式：最多 2000 个字符
datetime	字符串	消息的计划发送时间，采用 ISO 8601 格式
notification_type	字符串	仅限 Bot 模式：extension、whatsapp 或 automatic（默认值）

download_media

下载并解密消息中的媒体（图片、视频、音频、文档）。

参数	类型	描述
message_id	字符串	包含媒体的消息 ID
conversation_id	字符串	该消息所属的会话

返回 base64 编码的媒体数据，包含 MIME 类型、大小、时长和说明文字。

manage_notes

读取和写入联系人备注（WhatsApp Business）。

Parameter	Type	Description
action	string	get、set
contact_id	string	联系人 ID
note	string	备注文本（set 时必填）

call_recordings

读取由 Kaption 扩展录制的 WhatsApp 通话录音及其转录文本，每个词都带有时间戳。每段录音都会标明对应的会话对象（通话的另一方；群组通话则为群组）。不会返回已锁定聊天的录音。

Parameter	Type	Description
action	string	list、get、search
id	string	录音 ID（get 时必填）
search	string	在名称和转录文本中查找的文本（search 时必填）
conversation_id	string	仅返回此联系人或群组的录音
date_from / date_to	string	通话开始时间的 ISO 8601 日期范围
limit	number	录音数量上限（默认 20，最多 100）
include_words	boolean	用于 get：返回每个词及其开始和结束时间（秒）

get_api_info

获取 HTTP REST API 连接信息，以便在不使用 MCP 的情况下进行程序化访问。返回 URL、身份验证令牌和可用端点。

多账户支持

可以同时连接多个 WhatsApp 账户（例如个人账户和商务账户）。在任意工具上使用 target_session，即可将请求路由到特定账户。查询 entity: "session" 可查看所有已连接账户及其会话 ID。

多实例支持

多个 AI 工具可以共用同一个扩展连接。第一个实例会启动 WebSocket 集线器；后续实例会自动检测现有集线器并通过它中继。如果集线器停止运行，中继实例会自动接管。

WebMCP 支持

Kaption 已支持 WebMCP。在支持 W3C WebMCP 草案（navigator.modelContext，Chrome 146+）的浏览器中，扩展会自动将所有工具注册到浏览器原生 AI 工具注册表中。这意味着基于浏览器的 AI Agent 无需 MCP 服务或 WebSocket 连接，即可发现并调用 Kaption 工具，无需任何配置。

WebMCP 可用时，扩展会注册带有 kaption_ 前缀的工具（例如 kaption_query、kaption_manage_chat），并附带 JSON Schema 输入定义和 readOnlyHint 注释。这些工具使用与 MCP 服务相同的处理程序，因此两种调用方式的行为一致。

安全性

• 仅限 localhost — 不使用云中继，也不建立外部连接
• 不发送消息 — AI 助手可以读取、整理、安排和起草消息，但绝不会直接发送消息
• 隐藏已锁定聊天 — 所有查询都不会包含 WhatsApp 锁定的会话
• 功能需显式启用 — 必须在扩展中明确启用 MCP 桥接
• 限制商务功能 — 标签和备注需要 WhatsApp Business 账户
• 限制请求频率 — 起草消息的范围限制为每 5 分钟最多 10 个会话；写入操作会加入随机延迟

许可证

BSL 1.1 — 可免费使用，4 年后转换为 MIT 许可证。

一次性附件（仅所有者可用的 MCP_LOCAL_SEND）

使用 create_attachment_upload({name,mime,size,target_session?})，在 15 分钟内将文件字节 PUT 到 其 uploadUrl，然后在一小时内发送 attachment:{ref:attachmentRef}。选定的 Kaption 账户会使用该引用一次并将其存储在本地，因此几天后的计划任务不依赖临时上传。如果下载在使用该引用后失败，请创建新的上传。最大大小：8 MiB；支持图片、文档、音频或视频。

在此本地中枢上，attachment:{path:"/absolute/file.pdf"} 会自动上传；可选的 name 和 mime 参数可覆盖文件名和类型。路径必须指向常规文件。云中继和 WebMCP 不接受路径。绝不接受任意 URL。现有的小型内联 {name,mime,size,dataB64} 上传方式仍可继续使用。所有发送仍需遵守扩展程序的仅所有者标记、同意和优先询问规则。任何助手都无法代为同意。