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)
Read and manage your WhatsApp conversations through the KaptionAI browser extension.
2026-11-09
ดาว
—
เครื่องมือ
—
อัปไทม์
—
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):
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: "[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" }
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: "[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…" }
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 URL, auth token, and available endpoints.
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 (owner-only MCP_LOCAL_SEND)
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 the
extension's owner-only flag, consent and ask-first rules. No assistant can accept consent.