{"id":50422480,"url":"https://github.com/kahflane/whatsapp-mcp","last_synced_at":"2026-05-31T09:02:06.291Z","repository":{"id":361438462,"uuid":"1254463016","full_name":"kahflane/whatsapp-mcp","owner":"kahflane","description":"Give your AI agent a WhatsApp account — an MCP server with 87 tools for reading, sending, groups, status, scheduling \u0026 more. Works with Claude, Codex, Cursor, OpenCode \u0026 any MCP client.","archived":false,"fork":false,"pushed_at":"2026-05-30T15:58:30.000Z","size":125,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T17:23:23.587Z","etag":null,"topics":["ai-agents","baileys","bun","claude","claude-code","codex","cursor","llm","mcp","mcp-server","model-context-protocol","opencode","typescript","whatsapp","whatsapp-api"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kahflane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-30T15:43:43.000Z","updated_at":"2026-05-30T15:58:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kahflane/whatsapp-mcp","commit_stats":null,"previous_names":["kahflane/whatsapp-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kahflane/whatsapp-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kahflane%2Fwhatsapp-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kahflane%2Fwhatsapp-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kahflane%2Fwhatsapp-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kahflane%2Fwhatsapp-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kahflane","download_url":"https://codeload.github.com/kahflane/whatsapp-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kahflane%2Fwhatsapp-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33725060,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","baileys","bun","claude","claude-code","codex","cursor","llm","mcp","mcp-server","model-context-protocol","opencode","typescript","whatsapp","whatsapp-api"],"created_at":"2026-05-31T09:02:04.043Z","updated_at":"2026-05-31T09:02:06.285Z","avatar_url":"https://github.com/kahflane.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 📱 WhatsApp MCP\n\n**Give your AI agent a WhatsApp account.**\n\nRead, search, send, schedule, and manage WhatsApp — all through the [Model Context Protocol](https://modelcontextprotocol.io). 87 tools, one process (Node or Bun), your messages in local SQLite.\n\nWorks with **any MCP client** — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Copilot), OpenAI Codex CLI, OpenCode, Cline, Zed, Goose, and more.\n\n[![Release](https://img.shields.io/github/v/release/kahflane/whatsapp-mcp?style=for-the-badge\u0026logo=github)](https://github.com/kahflane/whatsapp-mcp/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](LICENSE)\n[![Node](https://img.shields.io/badge/Node-18+-339933?style=for-the-badge\u0026logo=node.js\u0026logoColor=white)](https://nodejs.org)\n[![Bun](https://img.shields.io/badge/Bun-1.1+-000000?style=for-the-badge\u0026logo=bun\u0026logoColor=white)](https://bun.sh)\n[![MCP](https://img.shields.io/badge/MCP-compatible-6E56CF?style=for-the-badge)](https://modelcontextprotocol.io)\n\n\u003c/div\u003e\n\n---\n\n\u003e [!WARNING]\n\u003e **Use a dedicated/burner number.** This is unofficial automation and violates WhatsApp's Terms of Service — your account *can* be banned. Never connect your primary line. New numbers should warm up slowly (~20 messages/day for the first week). You accept this risk.\n\n---\n\n## ✨ What you can do\n\nAsk your assistant things like:\n\n\u003e *“What did the design team say in the group chat today?”*\n\u003e *“Send the invoice template to +60123456789 with order #4471.”*\n\u003e *“Schedule a birthday message to Rimu for 9am tomorrow.”*\n\u003e *“Who voted for option B in yesterday's poll?”*\n\u003e *“Post a status to my close friends with this photo.”*\n\nIt just works — your assistant drives WhatsApp on your behalf.\n\n## 🎯 Features\n\n| | |\n|---|---|\n| 💬 **Messaging** | Text, media, location, contacts, polls, events, reactions, edits, replies, forwards, pins |\n| 🔎 **Read \u0026 search** | Full-text search your whole history offline — chats, contacts, unread, media download |\n| 👥 **Groups** | Create, manage members, admin controls, invite links, join requests, metadata |\n| 📣 **Status / Story** | Rich text (backgrounds + fonts), image, video, gif, voice — to contacts **and** groups |\n| 🗂️ **Chat management** | Archive, pin, mute, star, mark read, disappearing messages |\n| 🔐 **Profile \u0026 privacy** | Name, about, avatar, block list, privacy settings, presence |\n| ⏰ **Automation** | Scheduled messages, reusable templates, keyword auto-replies |\n| 🧩 **Interactive** | Buttons, lists, and commerce (product/order) messages |\n| 🛡️ **Safety built-in** | Anti-ban send pacing, daily cap, and a one-flip **kill-switch** for all sends |\n\n**[→ See all 87 tools](#-tool-reference)**\n\n## 🚀 Quick start\n\n### 1. Add it to your agent\n\nNo install, no token, no path — `npx` (or `bunx`) fetches and runs it on demand. Pick your client below.\n\n\u003e Requires [Node 18+](https://nodejs.org) (for `npx`) **or** [Bun](https://bun.sh) (for `bunx`). Using Bun instead? Swap `npx -y` for `bunx` in any command below.\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nclaude mcp add whatsapp -- npx -y @kahflane/whatsapp-mcp\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOpenAI Codex CLI\u003c/b\u003e\u003c/summary\u003e\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.whatsapp]\ncommand = \"npx\"\nargs = [\"-y\", \"@kahflane/whatsapp-mcp\"]\nenv = { WA_PAIRING_NUMBER = \"\", WA_SYNC_FULL_HISTORY = \"true\", WA_DAILY_CAP = \"100\" }\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOpenCode\u003c/b\u003e\u003c/summary\u003e\n\nAdd to `opencode.json` (or `~/.config/opencode/opencode.json`):\n\n```json\n{\n  \"mcp\": {\n    \"whatsapp\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@kahflane/whatsapp-mcp\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor / Windsurf / Cline / Zed\u003c/b\u003e\u003c/summary\u003e\n\nThese read a JSON MCP block (Cursor: `~/.cursor/mcp.json`, Windsurf: `~/.codeium/windsurf/mcp_config.json`, Cline: its MCP settings, Zed: `settings.json` under `context_servers`):\n\n```json\n{\n  \"mcpServers\": {\n    \"whatsapp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@kahflane/whatsapp-mcp\"],\n      \"env\": { \"WA_PAIRING_NUMBER\": \"\", \"WA_SYNC_FULL_HISTORY\": \"true\", \"WA_DAILY_CAP\": \"100\" }\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Desktop / VS Code Copilot / Goose / any other MCP client\u003c/b\u003e\u003c/summary\u003e\n\nAdd the same server block to your client's config (Claude Desktop: `claude_desktop_config.json`, VS Code: `.vscode/mcp.json`, Goose: its extensions config):\n\n```json\n{\n  \"mcpServers\": {\n    \"whatsapp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@kahflane/whatsapp-mcp\"],\n      \"env\": {\n        \"WA_PAIRING_NUMBER\": \"\",\n        \"WA_SYNC_FULL_HISTORY\": \"true\",\n        \"WA_DAILY_CAP\": \"100\"\n      }\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePrefer to run from source?\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/kahflane/whatsapp-mcp.git\ncd whatsapp-mcp \u0026\u0026 bun install\n# then point your client at:  bun run /ABSOLUTE/PATH/TO/whatsapp/src/index.ts\n```\n\u003c/details\u003e\n\n### 2. Log in\n\nRestart your MCP client, then just ask your assistant to connect:\n\n1. **“Check WhatsApp status”** → it calls `wa_status`.\n2. **“Show me the login QR”** → it calls `wa_get_login_qr`. Scan it in **WhatsApp ▸ Settings ▸ Linked Devices**.\n   *(Prefer a code? Set `WA_PAIRING_NUMBER` and ask for the pairing code instead.)*\n3. **“Check status again”** → reads `open`. Your history starts syncing into local SQLite.\n\nAuth persists — **you only do this once.** 🎉\n\n## 🧠 How it works\n\nOne process is *both* the MCP server and the WhatsApp client — a single long-lived WebSocket shared by every tool, with everything stored in local SQLite.\n\n```\n  Your AI assistant\n        │  stdio (JSON-RPC)\n        ▼\n┌──────────────────────────────────────────────┐\n│  whatsapp-mcp  (one Node/Bun process)         │\n│                                               │\n│   MCP Server  ◄──►  Baileys WhatsApp socket   │\n│        │                     │                 │\n│        └────────►  SQLite ◄──┘                 │\n│              (contacts · chats · messages)     │\n└──────────────────────────────────────────────┘\n```\n\n- **Local-first** — your full history lives on your machine in SQLite. Reading \u0026 search work offline.\n- **Private** — auth credentials and your message database never leave your computer.\n- **Safe by default** — every send is paced with jittered delays + a daily cap, and can be frozen instantly with the kill-switch.\n\n## ⚙️ Configuration\n\nAll optional, set via environment variables (see [`.env.example`](.env.example)):\n\n| Variable | Default | Description |\n|---|---|---|\n| `WA_PAIRING_NUMBER` | *(empty)* | Set a number to log in by code instead of QR |\n| `WA_SYNC_FULL_HISTORY` | `true` | Pull full chat history on first sync |\n| `WA_DAILY_CAP` | `100` | Max sends per day (anti-ban) |\n| `WA_MIN_GAP_MS` / `WA_MAX_GAP_MS` | — | Jittered delay window between sends |\n| `WA_DATA_DIR` | `~/.whatsapp-mcp` | Where auth, database + media live (`WA_AUTH_DIR` / `WA_DB_PATH` / `WA_MEDIA_DIR` default under it) |\n| `WA_LOG_LEVEL` | `warn` | Log verbosity (to stderr) |\n\n## 🧰 Tool reference\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eConnection \u0026 login\u003c/b\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|---|---|\n| `wa_status` | Connection, login state, store stats, send counters |\n| `wa_get_login_qr` · `wa_get_pairing_code` | First-time login |\n| `wa_logout` | Log out and wipe local auth |\n| `wa_restrict_sending` | 🛑 Kill-switch — block/allow all outbound sends |\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eReading \u0026 search\u003c/b\u003e (works offline)\u003c/summary\u003e\n\n| Tool | Description |\n|---|---|\n| `wa_list_chats` | List chats, newest first |\n| `wa_list_contacts` · `wa_resolve_name` | Contacts + name resolution |\n| `wa_get_messages` | Read a chat's full messages |\n| `wa_search_messages` | Full-text search your history |\n| `wa_get_unread` · `wa_mark_read` | Unread tracking + read receipts |\n| `wa_fetch_history` | Pull older history (50/call) |\n| `wa_history_status` | Sync progress |\n| `wa_download_media` | Download + decrypt media to a file |\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSending\u003c/b\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|---|---|\n| `wa_check_number` | Verify numbers are on WhatsApp (anti-ban precheck) |\n| `wa_send_text` | Text with mentions / reply / typing |\n| `wa_send_media` | Image, video, audio, document, sticker |\n| `wa_send_location` · `wa_send_contact` | Location pin · contact card(s) |\n| `wa_send_poll` · `wa_get_poll_votes` | Send a poll · read decrypted vote tallies |\n| `wa_send_event` | Event card |\n| `wa_send_buttons` · `wa_send_list` | Interactive buttons + list messages |\n| `wa_react` · `wa_edit_message` · `wa_delete_message` | Modify messages |\n| `wa_forward_message` · `wa_pin_message` | Forward · pin in chat |\n| `wa_send_broadcast` · `wa_broadcast_info` | Broadcast to a list · query a list |\n| `wa_send_product` · `wa_send_order` | Commerce messages (Business accounts) |\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eStatus / Story\u003c/b\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|---|---|\n| `wa_post_status` | Post a story mentioning up to 5 contacts |\n| `wa_post_status_to` | Post to a chosen audience (contacts **and** groups) — text with rich backgrounds + fonts, image, video, gif, voice note, audio |\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eChat management\u003c/b\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|---|---|\n| `wa_archive_chat` · `wa_pin_chat` · `wa_mute_chat` | Archive · pin · mute (and undo) |\n| `wa_mark_chat_read` · `wa_star_message` | Mark read/unread · star a message |\n| `wa_delete_chat` · `wa_delete_message_for_me` | Delete chat · clear a message locally |\n| `wa_disappearing_chat` | Per-chat disappearing-message timer |\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGroups\u003c/b\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|---|---|\n| `wa_create_group` · `wa_groups_list` · `wa_group_metadata` | Create · list all · full metadata |\n| `wa_get_group_members` | Participants with names + admin flags |\n| `wa_group_participants` | Add / remove / promote / demote |\n| `wa_group_update_subject` · `wa_group_update_description` | Rename · set description |\n| `wa_group_setting` · `wa_group_add_mode` · `wa_group_ephemeral` | Announce-lock · who-can-add · disappearing |\n| `wa_group_invite_code` · `wa_group_join` · `wa_group_info_by_code` | Invite links · join · preview by code |\n| `wa_group_join_requests` · `wa_group_join_decision` | List · approve/reject requests |\n| `wa_group_member_label` · `wa_group_leave` | Label a member · leave group |\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eProfile, privacy \u0026 presence\u003c/b\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|---|---|\n| `wa_set_name` · `wa_set_status` · `wa_set_picture` · `wa_remove_picture` | Manage your own profile |\n| `wa_block` · `wa_blocklist` | Block/unblock · list blocked |\n| `wa_get_privacy` · `wa_set_privacy` · `wa_default_disappearing` | Read/set privacy + default timer |\n| `wa_get_status` · `wa_get_picture_url` · `wa_get_business_profile` | Someone's about · avatar · business profile |\n| `wa_subscribe_presence` · `wa_send_presence` | Subscribe to · broadcast presence |\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCalls · Scheduling · Templates · Auto-reply\u003c/b\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|---|---|\n| `wa_reject_call` | Reject an incoming call |\n| `wa_schedule_message` · `wa_list_scheduled` · `wa_cancel_scheduled` | Schedule sends (persisted, fires exactly once) |\n| `wa_list_templates` · `wa_render_template` · `wa_create_template` · `wa_send_template` | Reusable message templates |\n| `wa_autoreply_set` · `wa_autoreply_add_rule` · `wa_autoreply_list_rules` · `wa_autoreply_remove_rule` | Keyword/pattern auto-replies (off by default) |\n\u003c/details\u003e\n\n## 💡 Good to know\n\n- **Only one server may run at a time** — it owns the auth dir + database. After changing config, restart your MCP client to respawn it.\n- **History** arrives in chunks after login; `wa_fetch_history` pages older messages 50 at a time (WhatsApp may not always relay on-demand history to linked devices).\n- **Pacing reduces, not eliminates, ban risk.** Respect the daily cap and warm up new numbers slowly.\n- **Auto-reply is OFF by default.** Enable it explicitly with `wa_autoreply_set`.\n\n## 🛠️ Tech\n\n[Node](https://nodejs.org) · [Bun](https://bun.sh) · [node-sqlite3-wasm](https://github.com/tndrle/node-sqlite3-wasm) · [bun:sqlite](https://bun.sh/docs/api/sqlite) · [@innovatorssoft/baileys](https://github.com/innovatorssoft/Baileys) · [Anthropic MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) · TypeScript\n\n## 🤝 Contributing\n\nIssues and PRs welcome. Run `bun run typecheck` and `bun run build` before submitting — they're the verification gates.\n\n## 📄 License\n\n[MIT](LICENSE) © KahfLane\n\n\u003cdiv align=\"center\"\u003e\n\u003csub\u003eNot affiliated with or endorsed by WhatsApp or Meta. Use responsibly and at your own risk.\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkahflane%2Fwhatsapp-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkahflane%2Fwhatsapp-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkahflane%2Fwhatsapp-mcp/lists"}