@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)

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

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

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

| 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. Only works for 1:1 chats.

# List pending messages
manage_scheduled_messages { action: "list" }

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

# Cancel a scheduled message
manage_scheduled_messages { action: "delete", id: "msg_abc123" }

| Parameter | Type | Description | |-----------|------|-------------| | action | string | list, get, create, update, delete | | filter | string | For list: pending (default), sent, all | | id | string | Scheduled message ID (for get/update/delete) | | conversation_id | string | Contact/chat ID to send to (for create) | | message | string | Message text (max 800 chars, no newlines) | | datetime | string | ISO 8601 datetime when the message should be sent |

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) |

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.