Kaption WhatsApp

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

summarize_conversation

Generate a summary of a conversation.

manage_labels

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

manage_lists

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

Reading them is list_chat_lists / get_chat_list (read-only tools).

# List all custom lists (read-only tool)

list_chat_lists {}

Get a list with its chats (read-only tool)

get_chat_list { 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" }

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

manage_reminders

Create, change, complete or delete personal reminders. Stored in the cloud and delivered via the Kaption extension. Reading them is list_reminders / get_reminder (read-only tools).

# List active reminders (read-only tool)

list_reminders {}

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

list_reminders { filter: "all" }

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.

Reading them is list_scheduled_messages / get_scheduled_message (read-only tools).

# List pending messages of both modes (each one has a "mode") — read-only tool

list_scheduled_messages {}

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

download_media

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

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

manage_notes

Write a contact's note (WhatsApp Business). Reading it is get_contact_note { contact_id } (read-only tool).

| `no