Allows AI agents to search existing WhatsApp chats, read recent messages, summarize conversations, and draft or send replies with explicit one-time confirmation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@whatsapp-assistant Summarize recent messages in my project chat."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
WhatsApp Assistant is a local WhatsApp MCP server and agent plugin for Codex, Claude Code and other local MCP clients on macOS. Search selected existing chats, summarize recent text and prepare replies that require a separate confirmation before sending. The bridge uses a private Unix socket, not a local network port.
0.3.0 preview candidate (local source preparation, 2026-10-02) | macOS | native UI support unverified
The historical Codex Desktop path was live-tested with runtime 0.2.0 for status, selected-chat search/read and separately confirmed interactive text sending. The 0.3.0 candidate adds a bundled graphical UI for bounded text history and confirmed replies, including a user-selected image or file; fresh local plugin installation and Codex browser-panel rendering are verified; native host rendering and public listing are not yet verified. Claude Code, Claude Desktop, Cursor, VS Code and other MCP clients are experimental. Fresh plugin installation, recovery and real scheduled-send acceptance are not claimed. See the exact evidence.
Deutsch · Installation · Compatibility · FAQ · Privacy · Support · Contributing
The separate online development pilot starts the Dots roadmap. It provides a tested read-only HTTP MCP gateway and outbound device bridge, with explicit user/chat/account boundaries. It is not deployed, publicly installable, or live-verified with Dots. The local plugin and its six existing model tools remain unchanged.
For a personal Dot, the repository also contains an operator path through the
official Secure MCP Tunnel. The private
online/private-*.mjs path exposes three read tools by default; two text-write
tools are opt-in and require a separately confirmed preparation. All-chat access
is explicitly bound to the selected WhatsApp account, and reads stay within the
last 30 days. A durable ledger blocks repeated sends after both unknown and
successful outcomes. CONFIRMATION_REQUIRED, APPROVAL_INVALID,
ACCOUNT_CHANGED, CONNECTION_UNAVAILABLE and INVALID_ARGUMENTS are returned
as safe, distinguishable errors. This tunnel is private operator infrastructure,
not a public HTTPS deployment or an OpenAI directory submission.
The candidate includes a React UI for connection status, chat search, an unread filter, bounded text history, older-page loading and a two-step reply flow. Attach one image or file (up to 16 MiB) to a reply, with optional caption. Raster images show a preview; other files show their name and size. File bytes stay in local memory until the explicit send action and are not handed to the model. It resolves available chat and sender names, shows profile pictures with initials as fallback, and lets the user explicitly open received images and other bounded media. Text and file attachments are included only in the separately confirmed reply flow. It uses the same local MCP action layer and keeps view state in memory; it does not read session files or expose the Unix socket to the browser. Native Codex UI support is UNVERIFIED. A loopback browser panel can be started explicitly:
./plugins/whatsapp-assistant/scripts/run-ui.shThen open the printed loopback URL (by default
http://127.0.0.1:8765/) in the browser panel.
The UI does not start a daemon or link an account automatically. See the UI acceptance record, support and terms.
Find the chat you need, summarize recent messages, and draft a reply. Interactive replies require the exact recipient and text to be shown first, followed by a new explicit confirmation. Preauthorized scheduled tasks use separate, recipient-bound secret capabilities and durable duplicate prevention.
Scoped search and paginated text history, limited to the selected chat's last 30 days.
Model-facing tools remain text-only; the graphical UI opens selected media explicitly. No new numbers, bulk messaging, or incoming-triggered auto-replies.
Local Unix socket, private session storage, metadata-only logs, no plugin cloud relay.
Shared agent skill plus an MCP safety prompt for clients without plugin skills.
Pinned OpenWA runtime; remote runtime patches and insecure Chrome flags disabled.
“Local” describes the WhatsApp bridge, not the AI provider: tool results enter your chosen client's/model's context. See the privacy document before connecting.
Related MCP server: WhatsApp MCP for macOS
Consider this project when you want to find and summarize a selected WhatsApp chat from a local Codex or Claude workflow, or review a text reply before explicitly sending it. It is for users willing to run an unofficial Chrome/ OpenWA bridge on their own Mac and assess its account and provider risks.
It is not a WhatsApp Business Platform integration, offline AI, a bulk outreach tool or an unattended incoming-message bot. It is unsuitable when you need official vendor support, a cloud-only client or business-critical delivery. Common questions explain the trade-offs.
Requires macOS, Google Chrome, Node.js 22.13+ and pnpm 11.19.0. Review the source and the unofficial WhatsApp-account risk before running the setup script.
From a local checkout:
./plugins/whatsapp-assistant/scripts/install.shScan the QR code yourself in your terminal; never share it with an AI model or paste it into an issue. Then configure your client:
Codex marketplace registration:
codex plugin marketplace add .Install whatsapp-assistant from WhatsApp Assistant Community in the supported desktop plugin directory, then start a new task. Registration does not install the WhatsApp runtime or imply live acceptance.
Experimental Claude Code setup, from the repository root:
/plugin marketplace add .
/plugin install whatsapp-assistant@whatsapp-assistant-communityExperimental local MCP clients, including Claude Desktop and Cursor:
node plugins/whatsapp-assistant/scripts/mcp-config.mjs claude-desktop
node plugins/whatsapp-assistant/scripts/mcp-config.mjs cursorThese commands print an absolute-path configuration; they do not alter your
client settings. Merge it into the appropriate client configuration. Load the
whatsapp-safety MCP prompt or the bundled skill before using the tools.
Source repository: ckundel2008/whatsapp-agent-mcp. Use this local 0.3.0 candidate checkout for UI evaluation. Public directory publication is not complete and requires a public HTTPS endpoint and OpenAI review.
Evaluate the candidate from the local checkout with:
codex plugin marketplace add .
codex plugin add whatsapp-assistant@whatsapp-assistant-communityThe following remote commands apply after the updated source is published:
/plugin marketplace add ckundel2008/whatsapp-agent-mcp
/plugin install whatsapp-assistant@whatsapp-assistant-communitySynthetic example — not a captured WhatsApp conversation:
You: Summarize recent messages in my project chat.
Agent: [finds the selected existing chat, reads only the requested scope]
You: Draft “Thanks, I'll be there at 10.”
Agent: Recipient: Project chat (group)
Text: Thanks, I'll be there at 10.
Shall I send exactly this?
You: Yes, send it.
Agent: [uses the one-time approval; reports the confirmed message ID]This is a community project, not an official WhatsApp/Meta, OpenAI, or Anthropic integration. OpenWA/WhatsApp Web can change without notice, and unofficial automation can lead to account restrictions. Avoid business-critical reliance.
The MCP runtime and safety regressions are tested locally. The 0.3.0 source update is prepared locally as a preview candidate; no public HTTPS deployment or OpenAI submission has been made. Fresh plugin installation and live text-history rendering in the Codex browser panel passed. The actual private ChatGPT path has been checked for status, search, reading and send preparation. On 2026-10-03, the operator confirmed that real sending works in personal use. This is user-reported live acceptance, without an additional agent-initiated send or independent receipt check. Native Codex MCP-App rendering is also unverified; see the UI acceptance record. Other client packaging is experimental. Reboot, reauthentication, uninstall, real scheduled-send acceptance and independent receipt on another device remain untested. Windows, Linux runtime installation, remote/cloud-only clients, and mobile clients are unsupported.
The production audit is clean again after the 2026-10-03 security backports.
Two affected transitive packages are replaced by documented local repaired
forks, with regression tests, licenses and source integrity checks. See the
security backport record.
Publisher/repository is ckundel2008/whatsapp-agent-mcp, with MIT for own source.
Private vulnerability reporting is enabled on GitHub. Stable source publication
does not mean universal client acceptance or vendor-supported delivery;
dependencies retain their own obligations.
See Release checklist. This is not a zero-risk or fully
audited security product. Changelog · Security
Release notes and the client acceptance record keep tested facts separate from remaining checks. Dependency maintenance explains the pinned installed-Chrome workflow and unsupported manual browser downloads.
If this becomes useful in your workflow, a star helps others discover it. Useful bug reports and tested compatibility contributions help even more.
Maintained by ckundel2008, an independent community publisher. Project facts provide a plain JSON summary of purpose, requirements, suitability and evidence. llms.txt is an optional reading index, not a promise of indexing or AI recommendations. Discovery maintenance distinguishes searchable documentation from actual citation and recommendation measurements.
The same publisher also maintains Codex Stream Deck, a separate macOS bridge for Codex task keys, shortcuts and weekly allowance on Elgato hardware. It is not required by WhatsApp Assistant and is not a Claude/MCP bridge.
The project's own code is under MIT. OpenWA and other dependencies keep their own licenses; see third-party notices.
This server cannot be deployed
Your own WhatsApp in Claude and ChatGPT: read chats, draft replies, send messages you approve.
Read, search and reply to your WhatsApp chats from your AI, using your own number.
WhatsApp for Claude, ChatGPT or any AI agent: search, reply and send. Personal or Business API.
Read-only WhatsApp MCP for your AI agent: it reads the chats you choose. Try the public demo.