Kaption WhatsApp

@kaptionai/mcp-extension

KaptionAI の Chrome 拡張機能を通じて、AI アシスタントが WhatsApp の会話を読み取り、管理できる MCP サーバーです。また、設定不要でブラウザー標準の AI ツールを検出できる WebMCP にも対応しています。

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

エージェントスキル

Claude Code、Codex、Cursor などのエージェントに、これらのツールを適切に使う方法を教えます（最初に検索する、確認せずに送信しない、リマインダーと予約メッセージを使い分ける、エラーに対処する）。

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	string	archive、unarchive、mark_read、mark_unread、pin、unpin、mute、unmute、set_draft、clear_draft
conversation_id	string	会話 ID
mute_duration	string	8h、1w、または forever（デフォルト）。mute の場合のみ
text	string	下書きテキスト。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	string	list、get、create、update、delete、complete、uncomplete
filter	string	list の場合：active（デフォルト）、completed、all
id	string	リマインダー ID（get／update／delete／complete／uncomplete 用）
title	string	リマインダーのテキスト（最大 800 文字、改行不可）
datetime	string	ISO 8601 形式の日時
notification_type	string	extension、whatsapp、または automatic（デフォルト）

manage_scheduled_messages

次の 2 つのモードのいずれかで、指定した時刻にメッセージが自動送信されるようにスケジュールします。

• bot（デフォルト）— あなたの番号ではなく、Kaption の WhatsApp 番号から送信されます。Kaption のクラウドに保存され、コンピューターの電源が切れていても送信されます。1 対 1 のチャットのみ。1 行、最大 800 文字です。
• local（「このコンピューターから」）— コンピューターと WhatsApp を開いている間、あなたとして、あなた自身の WhatsApp 番号から送信されます。デバイスから外部にデータが送信されることはありません。Kaption は安全な制限（1 時間および 1 日あたり数件、数分間隔、相手が書き込んだチャットのみ、グループには 1 日最大 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	string	list、get、create、update、delete。mode: "local" の場合は cancel、remove（完了済みのもの）、send_now（送信漏れまたは失敗したもの）も指定できます
mode	string	bot（デフォルト）または local。list の場合、省略すると両方のモードが対象になります
filter	string	list の場合：pending（デフォルト）、sent、all
id	string	スケジュール済みメッセージ ID（get／update／delete／cancel／remove／send_now 用）
conversation_id	string	送信先のチャット（create の場合）：個人、または mode: "local" の場合はグループ
message	string	メッセージテキスト。Bot：最大 800 文字、改行不可。Local：最大 2000 文字
datetime	string	メッセージの送信日時（ISO 8601 形式）
notification_type	string	Bot のみ：extension、whatsapp、または automatic（デフォルト）

download_media

メッセージ内のメディア（画像、動画、音声、ドキュメント）をダウンロードして復号します。

パラメーター	型	説明
message_id	string	メディアを含むメッセージの ID
conversation_id	string	メッセージが属する会話

MIME タイプ、サイズ、再生時間、キャプションとともに、Base64 でエンコードされたメディアデータを返します。

manage_notes

連絡先のメモを読み書きします（WhatsApp Business）。

パラメーター	型	説明
action	string	get、set
contact_id	string	連絡先 ID
note	string	メモのテキスト（set で必須）

call_recordings

Kaption 拡張機能で録音された WhatsApp 通話と、その文字起こしを読み込みます。すべての単語にタイムスタンプが付いています。各録音には会話相手（グループ通話の場合はグループ）の名前が付いています。ロックされたチャットの録音は返されません。

パラメーター	型	説明
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

MCP のオーバーヘッドなしでプログラムからアクセスするための HTTP REST API 接続情報を取得します。URL、認証トークン、利用可能なエンドポイントを返します。

複数アカウントのサポート

複数の WhatsApp アカウントを同時に接続できます（例：個人用とビジネス用）。任意のツールで target_session を使うと、特定のアカウントにルーティングできます。entity: "session" をクエリすると、接続中のすべてのアカウントとそのセッション ID を確認できます。

複数インスタンスのサポート

複数の AI ツールで同じ拡張機能の接続を共有できます。最初のインスタンスが WebSocket ハブを起動し、後続のインスタンスは既存のハブを自動検出して、それを経由して中継します。ハブが停止すると、中継側のインスタンスが自動的に昇格します。

WebMCP のサポート

Kaption は WebMCP に対応しています。W3C WebMCP ドラフト（navigator.modelContext、Chrome 146+）をサポートするブラウザーでは、拡張機能がすべてのツールをブラウザーのネイティブ AI ツールレジストリに自動登録します。これにより、ブラウザー上の AI エージェントは MCP サーバーや WebSocket 接続なしで Kaption ツールを検出して呼び出せます。設定は不要です。

WebMCP が利用可能な場合、拡張機能は kaption_ を接頭辞とするツール（例：kaption_query、kaption_manage_chat）を、JSON Schema の入力定義と readOnlyHint 注釈とともに登録します。これらのツールは MCP サーバーと同じハンドラーを使うため、どちらの経路でも動作は同一です。

セキュリティ

• ローカルホストのみ — クラウドリレーや外部接続はありません
• メッセージは送信されません — AI アシスタントはメッセージの読み取り、整理、スケジュール設定、下書き作成ができますが、メッセージを直接送信することはありません
• ロックされたチャットは非表示 — WhatsApp でロックされた会話は、すべてのクエリから除外されます
• 機能の有効化が必要 — MCP ブリッジは拡張機能で明示的に有効にする必要があります
• ビジネス機能は制限されています — ラベルとメモの利用には WhatsApp Business アカウントが必要です
• レート制限あり — メッセージの下書きは 5 分間に 10 件の会話までに制限され、書き込み操作にはランダムな遅延が含まれます

ライセンス

BSL 1.1 — 無料で利用でき、4 年後に MIT ライセンスに切り替わります。

1回限りの添付ファイル（所有者専用 MCP_LOCAL_SEND）

create_attachment_upload({name,mime,size,target_session?}) を使い、15 分以内に uploadUrl に ファイルのバイトデータを PUT してから、1 時間以内に attachment:{ref:attachmentRef} を送信します。 選択した Kaption アカウントはこの参照を一度だけ使用し、ローカルに保存するため、数日後の スケジュール実行でも一時アップロードに依存しません。消費後にダウンロードが失敗した場合は、 新しいアップロードを作成してください。最大サイズ：8 MiB。画像、ドキュメント、音声、動画に対応しています。

このローカルハブでは、attachment:{path:"/absolute/file.pdf"} を使うと自動的にアップロードされます。 name と mime は任意で指定でき、ファイル名や種類を上書きします。パスには通常のファイルを指定する 必要があります。クラウドリレーと WebMCP ではパスを受け付けません。任意の URL は一切受け付けません。 既存の小さなインライン形式 {name,mime,size,dataB64} によるアップロードも引き続き利用できます。 すべての送信には、引き続き拡張機能の所有者専用フラグ、同意、および最初に確認するルールが適用されます。 アシスタントは同意を受け付けることができません。