使用说明

@kaptionai/mcp-extension

MCP server that lets AI assistants read and manage your WhatsApp conversations through the KaptionAI Chrome extension. Also supports WebMCP for zero-config browser-native AI tool discovery.

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

Agent skill

Teach Claude Code, Codex, Cursor and other agents how to use these tools well (search first, never send without confirming, reminders vs. scheduled messages, error handling):

npx skills add Kaption-AI/mcp-extension

The skill lives in skills/kaption-whatsapp/SKILL.md.

Setup

1. Install the extension

Install the KaptionAI Chrome Extension and enable the MCP bridge in settings.

2. Configure your AI tool

Claude Desktop

Add to ~/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

Add to .cursor/mcp.json in your project or go to Settings > MCP Servers:

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

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

VS Code (Copilot)

Add to .vscode/mcp.json in your project:

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

Or add to your VS Code settings.json:

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

Zed

Add to Zed settings (~/.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],
)

Any MCP-compatible client

This package runs as a standard MCP server over stdio. To connect from any client:

npx -y @kaptionai/mcp-extension@latest

The server communicates via stdin/stdout using the MCP protocol. Point your client's MCP configuration to this command.

3. Open WhatsApp Web

Open web.whatsapp.com in Chrome or Edge. The extension will auto-connect to the MCP server.

Tools

`query`

Query WhatsApp data — conversations, contacts, messages, transcriptions, labels, and communities.

# List conversations
query {}

# Search everything
query { query: "meeting" }

# Unread only
query { unread: true }

# Look up a conversation with messages
query { id: "5511999887766@c.us" }

# 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" }

Parameter	Type	Description
`query`	string	Search text (names, messages, transcriptions)
`id`	string	Look up a specific conversation, contact, or label
`entity`	string	`conversations`, `contacts`, `messages`, `transcriptions`, `labels`, `communities`, `session`
`limit`	number	Max results (default 25, max 5000)
`unread`	boolean	Only unread conversations
`label`	string	Filter by label name or ID
`community`	string	Filter by community name or ID
`before`	string	Messages before this ISO 8601 timestamp (pagination)
`after`	string	Messages after this ISO 8601 timestamp (incremental sync)

`summarize_conversation`

Generate a summary of a conversation.

Parameter	Type	Description
`conversation_id`	string	The conversation ID

`manage_labels`

Manage WhatsApp Business labels — add, remove, create, or delete labels.

Parameter	Type	Description
`action`	string	`add`, `remove`, `create`, `delete`
`label_name`	string	Label name
`label_id`	string	Label ID (alternative to name)
`conversation_id`	string	Required for add/remove

`manage_lists`

Manage personal chat lists (custom lists). The personal account equivalent of Business labels — organize chats into custom categories.

# 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: "5511999887766@c.us" }

# Add a chat to a list
manage_lists { action: "add_chat", name: "Family", conversation_id: "5511999887766@c.us" }

# Remove a chat from a list
manage_lists { action: "remove_chat", name: "Family", conversation_id: "5511999887766@c.us" }

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

Parameter	Type	Description
`action`	string	`list`, `get`, `create`, `edit`, `delete`, `add_chat`, `remove_chat`
`id`	string	List ID
`name`	string	List name (for create/edit, or to resolve by name)
`conversation_id`	string	Chat ID(s) to add/remove

`manage_chat`

Manage chat state — archive, unarchive, mark as read/unread, pin, unpin, mute, unmute, set/clear draft messages.

# Archive a chat
manage_chat { action: "archive", conversation_id: "5511999887766@c.us" }

# Mark as read
manage_chat { action: "mark_read", conversation_id: "5511999887766@c.us" }

# Pin a chat (max 3)
manage_chat { action: "pin", conversation_id: "5511999887766@c.us" }

# Mute for 1 week
manage_chat { action: "mute", conversation_id: "5511999887766@c.us", mute_duration: "1w" }

# Set a draft message
manage_chat { action: "set_draft", conversation_id: "5511999887766@c.us", text: "Hey, I'll call you back" }

Parameter	Type	Description
`action`	string	`archive`, `unarchive`, `mark_read`, `mark_unread`, `pin`, `unpin`, `mute`, `unmute`, `set_draft`, `clear_draft`
`conversation_id`	string	The conversation ID
`mute_duration`	string	`8h`, `1w`, or `forever` (default). Only for `mute`
`text`	string	Draft text. Required for `set_draft`

`manage_reminders`

Create and manage personal reminders. Stored in the cloud and delivered via the Kaption extension.

# 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" }

Parameter	Type	Description
`action`	string	`list`, `get`, `create`, `update`, `delete`, `complete`, `uncomplete`
`filter`	string	For list: `active` (default), `completed`, `all`
`id`	string	Reminder ID (for get/update/delete/complete/uncomplete)
`title`	string	Reminder text (max 800 chars, no newlines)
`datetime`	string	ISO 8601 datetime
`notification_type`	string	`extension`, `whatsapp`, or `automatic` (default)

`manage_scheduled_messages`

Schedule messages to be sent automatically at a specific time, in one of two modes:

bot (default) — sent from Kaption's WhatsApp number, not yours. Stored in Kaption's cloud and sent even when your computer is off. One-to-one chats only; one line, up to 800 characters.
local ("From this computer") — sent from your own WhatsApp number, as you, while this computer and WhatsApp are open. Nothing leaves your device. Kaption keeps it within safe limits automatically (a few messages an hour and a day, minutes apart, only to chats where the other person has written, at most 3 a day to groups) and refuses what doesn't fit, with the reason. The only mode that can send to groups (ones you can post in and posted in within the last 30 days). Text only. A message whose time passes while the computer is off is marked missed, never sent late on its own.

The local mode has to be turned on by you in Kaption first (the "From this computer" option in the scheduling picker, after reading the limits and risks). An AI assistant can't turn it on; until you do, local requests are refused with (reason: no-consent). It is also rolled out gradually: where it isn't available yet, local requests are refused with (reason: flag-off) and the bot works as before.

# 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: "5511999887766@c.us" }

# 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: "5511999887766@c.us" }
manage_scheduled_messages { action: "create", mode: "local", message: "Standup moved to 10", datetime: "2026-03-07T09:00:00Z", conversation_id: "120363000000000000@g.us" }

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

Parameter	Type	Description
`action`	string	`list`, `get`, `create`, `update`, `delete`; with `mode: "local"` also `cancel`, `remove` (a finished one), `send_now` (a missed or failed one)
`mode`	string	`bot` (default) or `local`. For `list`, omit to get both modes
`filter`	string	For list: `pending` (default), `sent`, `all`
`id`	string	Scheduled message ID (for get/update/delete/cancel/remove/send_now)
`conversation_id`	string	Chat to send to (for create): a person, or a group with `mode: "local"`
`message`	string	Message text. Bot: max 800 chars, no newlines. Local: up to 2000 chars
`datetime`	string	ISO 8601 datetime when the message should be sent
`notification_type`	string	Bot only: `extension`, `whatsapp`, or `automatic` (default)

`download_media`

Download and decrypt media from a message (images, videos, audio, documents).

Parameter	Type	Description
`message_id`	string	The message ID containing media
`conversation_id`	string	The conversation the message belongs to

Returns base64-encoded media data with mimetype, size, duration, and caption.

`manage_notes`

Read and write contact notes (WhatsApp Business).

Parameter	Type	Description
`action`	string	`get`, `set`
`contact_id`	string	The contact ID
`note`	string	Note text (required for `set`)

`call_recordings`

Read WhatsApp call recordings made by the Kaption extension and their transcripts, with every word timed. Each recording names its conversation (the other person, or the group for a group call). Recordings of locked chats are never returned.

Parameter	Type	Description
`action`	string	`list`, `get`, `search`
`id`	string	Recording ID (required for `get`)
`search`	string	Text to find in names and transcripts (required for `search`)
`conversation_id`	string	Only recordings of this contact or group
`date_from` / `date_to`	string	ISO 8601 date range of when the call started
`limit`	number	Max recordings (default 20, max 100)
`include_words`	boolean	For `get`: each word with its start and end in seconds

`get_api_info`

Get HTTP REST API connection info for programmatic access without MCP overhead. Returns the URL, the available endpoints and where the auth token file is (~/.kaptionai/mcp-auth-token, readable only by your user). The token itself is never returned, so it never lands in a chat transcript.

Multi-account support

Multiple WhatsApp accounts can be connected simultaneously (e.g. personal + business). Use target_session on any tool to route to a specific account. Query entity: "session" to see all connected accounts and their session IDs.

Multi-instance support

Multiple AI tools can share the same extension connection. The first instance starts a WebSocket hub; subsequent instances auto-detect the existing hub and relay through it. If the hub stops, a relay automatically promotes itself.

WebMCP support

Kaption is WebMCP-ready. On browsers that support the W3C WebMCP draft (navigator.modelContext, Chrome 146+), the extension automatically registers all tools with the browser's native AI tool registry. This means browser-based AI agents can discover and invoke Kaption tools without any MCP server or WebSocket connection — zero configuration.

When WebMCP is available, the extension registers tools prefixed with kaption_ (e.g. kaption_query, kaption_manage_chat) complete with JSON Schema input definitions and readOnlyHint annotations. The tools use the same handlers as the MCP server, so behavior is identical across both paths.

Security

Localhost only — no cloud relay, no external connections
No messages sent — AI assistants can read, organize, schedule, and draft, but never send messages directly
Locked chats hidden — WhatsApp-locked conversations are excluded from all queries
Feature-gated — MCP bridge must be explicitly enabled in the extension
Business features gated — labels and notes require a WhatsApp Business account
Rate limited — draft messages limited to 10 conversations per 5-minute window; write operations include random delays

License

BSL 1.1 — free to use, converts to MIT after 4 years.

One-time attachments (when sending from this computer is on for the account)

Use create_attachment_upload({name,mime,size,target_session?}), PUT the file bytes to its uploadUrl within 15 minutes, then send attachment:{ref:attachmentRef} within one hour. The selected Kaption account consumes the ref once and stores it locally, so a schedule days later does not depend on the temporary upload. If a download fails after consumption, create a new upload. Maximum size: 8 MiB; image, document, audio or video.

On this local hub, attachment:{path:"/absolute/file.pdf"} uploads automatically; optional name and mime override the filename/type. Paths must name regular files. The cloud relay and WebMCP do not accept paths. Arbitrary URLs are never accepted. Existing small inline {name,mime,size,dataB64} uploads continue to work. All sends still require sending from this computer to be turned on for the account, consent and ask-first rules. No assistant can accept consent.

使用说明

@kaptionai/mcp-extension

Agent skill

Setup

1. Install the extension

2. Configure your AI tool

3. Open WhatsApp Web

Tools

query

summarize_conversation

manage_labels

manage_lists

manage_chat

manage_reminders

manage_scheduled_messages

download_media

manage_notes

call_recordings

get_api_info