{"_id":"@arvoretech/whatsapp-mcp","_rev":"5-0b9d4c4499dd854dfa5eaf60af60af8f","name":"@arvoretech/whatsapp-mcp","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@arvoretech/whatsapp-mcp","version":"0.1.0","keywords":["mcp","whatsapp","baileys","messaging","arvore"],"author":{"name":"Arvore"},"license":"MIT","_id":"@arvoretech/whatsapp-mcp@0.1.0","maintainers":[{"name":"joao.barros.arvore","email":"joao.barros@arvore.com.br"},{"name":"ricardoraposorfox","email":"ricardorbxx1@gmail.com"},{"name":"vitor.piovezan","email":"vitor.piovezan@arvore.com.br"}],"homepage":"https://github.com/arvoreeducacao/arvore-mcp-servers#readme","bugs":{"url":"https://github.com/arvoreeducacao/arvore-mcp-servers/issues"},"bin":{"whatsapp-mcp":"dist/index.js"},"dist":{"shasum":"af2a688c3efa5e7353e3b7dc0f3767a0dff971f4","tarball":"https://registry.npmjs.org/@arvoretech/whatsapp-mcp/-/whatsapp-mcp-0.1.0.tgz","fileCount":3,"integrity":"sha512-sTl+RmjJDVIiKLAL44ZJAnCw5rPlhtM4mRXwRcB4d5woe3nTVfWr8iAFxB60KbQpIQA0ffxYgjLIRoI9qsUGhQ==","signatures":[{"sig":"MEUCIQDjbHsSUUgURyXY0FAEClE0MaRLeauE3bczIeNma8n5xgIgTPpIPKMbuWbBm8DtMfm5opsow9GQn4IKYyrdi5iZA7s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":7970},"main":"dist/index.js","type":"module","_from":"file:arvoretech-whatsapp-mcp-0.1.0.tgz","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/**/*.ts","test":"vitest run","build":"tsc","start":"node dist/index.js","lint:fix":"eslint src/**/*.ts --fix","test:cov":"vitest run --coverage --passWithNoTests"},"_npmUser":{"name":"ricardoraposorfox","email":"ricardorbxx1@gmail.com"},"_resolved":"/tmp/ebe8d905a6586c08eeb760ef831009a7/arvoretech-whatsapp-mcp-0.1.0.tgz","_integrity":"sha512-sTl+RmjJDVIiKLAL44ZJAnCw5rPlhtM4mRXwRcB4d5woe3nTVfWr8iAFxB60KbQpIQA0ffxYgjLIRoI9qsUGhQ==","repository":{"url":"git+https://github.com/arvoreeducacao/arvore-mcp-servers.git","type":"git","directory":"packages/whatsapp"},"_npmVersion":"11.13.0","description":"WhatsApp MCP Server using Baileys for sending and reading messages from a single WhatsApp account","directories":{},"_nodeVersion":"26.1.0","dependencies":{"zod":"^3.22.4","pino":"^10.3.1","qrcode":"^1.5.4","baileys":"^7.0.0-rc.9","better-sqlite3":"^12.9.0","qrcode-terminal":"^0.12.0","@modelcontextprotocol/sdk":"~1.22.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/qrcode":"^1.5.5","@types/better-sqlite3":"^7.6.13","@types/qrcode-terminal":"^0.12.2"},"_npmOperationalInternal":{"tmp":"tmp/whatsapp-mcp_0.1.0_1779996216679_0.45992744253629025","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@arvoretech/whatsapp-mcp","version":"0.1.1","description":"WhatsApp MCP Server using Baileys for sending and reading messages from a single WhatsApp account","main":"dist/index.js","type":"module","publishConfig":{"access":"public"},"bin":{"whatsapp-mcp":"dist/index.js"},"scripts":{"build":"tsc","prepublishOnly":"npm run build","dev":"tsx src/index.ts","start":"node dist/index.js","test":"vitest run","test:cov":"vitest run --coverage --passWithNoTests","lint":"eslint src/**/*.ts","lint:fix":"eslint src/**/*.ts --fix"},"keywords":["mcp","whatsapp","baileys","messaging","arvore"],"author":{"name":"Arvore"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/arvoreeducacao/arvore-mcp-servers.git","directory":"packages/whatsapp"},"dependencies":{"@modelcontextprotocol/sdk":"~1.22.0","baileys":"^7.0.0-rc.9","better-sqlite3":"^12.9.0","pino":"^10.3.1","qrcode":"^1.5.4","qrcode-terminal":"^0.12.0","zod":"^3.22.4"},"devDependencies":{"@types/better-sqlite3":"^7.6.13","@types/qrcode":"^1.5.5","@types/qrcode-terminal":"^0.12.2"},"_id":"@arvoretech/whatsapp-mcp@0.1.1","gitHead":"ff58466c3b5c49b3fba163d81b24b7b67447813b","bugs":{"url":"https://github.com/arvoreeducacao/arvore-mcp-servers/issues"},"homepage":"https://github.com/arvoreeducacao/arvore-mcp-servers#readme","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-ZXEjjeUso/pVQG8zhhIidPRfcNc5NlwY7zxo2WZ5gxK5j25vm9pLbqr0v5D72Exo24J7r9nzf1lWryolqMXQAQ==","shasum":"6fc84f83b7f98d5e8699e36591a0cb2df25787fb","tarball":"https://registry.npmjs.org/@arvoretech/whatsapp-mcp/-/whatsapp-mcp-0.1.1.tgz","fileCount":18,"unpackedSize":91026,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIF5Qojh6CILAPBl/wgvSwh3tWr7/r1igrYpOBCfbcxEqAiEA4557wyknpl0sbfwZt+zR0QJzXfI0j2MI5/fx0CHzWRc="}]},"_npmUser":{"name":"joao.barros.arvore","email":"joao.barros@arvore.com.br"},"directories":{},"maintainers":[{"name":"joao.barros.arvore","email":"joao.barros@arvore.com.br"},{"name":"rafsouza","email":"rafasouza@protonmail.com"},{"name":"pedro.adas","email":"pedro.adas@gmail.com"},{"name":"guilhermebs","email":"guilhermebscontact@gmail.com"},{"name":"ricardoraposorfox","email":"ricardorbxx1@gmail.com"},{"name":"jott4","email":"jvgcunha2002@gmail.com"},{"name":"vitor.piovezan","email":"vitor.piovezan@arvore.com.br"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/whatsapp-mcp_0.1.1_1783464083071_0.4174123044508651"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-28T19:23:36.480Z","modified":"2026-07-07T22:41:23.416Z","0.1.0":"2026-05-28T19:23:36.838Z","0.1.1":"2026-07-07T22:41:23.208Z"},"bugs":{"url":"https://github.com/arvoreeducacao/arvore-mcp-servers/issues"},"author":{"name":"Arvore"},"license":"MIT","homepage":"https://github.com/arvoreeducacao/arvore-mcp-servers#readme","keywords":["mcp","whatsapp","baileys","messaging","arvore"],"repository":{"type":"git","url":"git+https://github.com/arvoreeducacao/arvore-mcp-servers.git","directory":"packages/whatsapp"},"description":"WhatsApp MCP Server using Baileys for sending and reading messages from a single WhatsApp account","maintainers":[{"name":"joao.barros.arvore","email":"joao.barros@arvore.com.br"},{"name":"rafsouza","email":"rafasouza@protonmail.com"},{"name":"pedro.adas","email":"pedro.adas@gmail.com"},{"name":"guilhermebs","email":"guilhermebscontact@gmail.com"},{"name":"ricardoraposorfox","email":"ricardorbxx1@gmail.com"},{"name":"jott4","email":"jvgcunha2002@gmail.com"},{"name":"vitor.piovezan","email":"vitor.piovezan@arvore.com.br"}],"readme":"# @arvoretech/whatsapp-mcp\n\nWhatsApp MCP server using [Baileys](https://github.com/WhiskeySockets/Baileys). Drives a single WhatsApp account from your AI agent over the official WhatsApp Web protocol.\n\n## What it does\n\n- Pairs a phone via QR code (one device, single user, multi-device protocol).\n- Sends and receives text, images, audio (PTT or normal), video, and documents.\n- Persists chat metadata, messages, and contacts in a local SQLite database so the agent can recall past conversations.\n- Exposes tools to set typing presence, mark messages as read, react, edit, and delete.\n\nAuth state lives at `~/.arvore-mcp/whatsapp/auth/` (override with `WHATSAPP_MCP_DATA_DIR`). The SQLite DB and pairing QR PNG live in the same folder.\n\n## First-time pairing\n\n1. Add the server to your MCP config (see below) and restart the agent.\n2. Ask the agent to call `connect`.\n3. The server prints an ASCII QR code to stderr and writes a PNG to `~/.arvore-mcp/whatsapp/qr.png`.\n4. Open WhatsApp on your phone, go to **Settings → Linked Devices → Link a Device** and scan the QR.\n5. After pairing, auth state is saved. Future `connect` calls reconnect silently.\n\nThe agent can also call `qr_code` to retrieve the pairing QR in `ascii`, `png` (file path), `data_url` (inline base64), or `raw` (the underlying string).\n\n## Tools\n\n| Tool | What it does |\n|------|--------------|\n| `connect` | Start the WhatsApp socket. Generates a QR code if no auth state exists. Set `waitForOpen=true` to block until paired. |\n| `status` | Report current connection state (`connecting`, `qr`, `open`, `close`), phone number, and QR availability. |\n| `qr_code` | Fetch the pairing QR in `ascii`, `png`, `data_url`, or `raw` form. |\n| `disconnect` | Close the socket without losing auth state. You can reconnect later without scanning QR. |\n| `logout` | Wipe local auth state. Requires `confirm: true`. The phone-side session must also be unlinked separately to fully revoke access. |\n| `send_text` | Send a text message. Supports replies via `quotedMessageId`. Brazilian numbers are normalized automatically. |\n| `send_media` | Send image, audio, video, or document via `filePath` (absolute path on disk) or `base64`. Audio defaults to push-to-talk. |\n| `send_reaction` | React to a message with an emoji. Pass an empty string to remove a previous reaction. |\n| `set_presence` | Set composing / paused / recording / available / unavailable for a chat. |\n| `mark_read` | Mark messages as read on WhatsApp and reset the local unread counter. |\n| `list_chats` | List recent chats with last message preview and unread count. |\n| `get_messages` | Fetch chat history (paginated by `beforeTimestamp`, oldest first). |\n| `search_messages` | Substring search across all stored messages. |\n| `search_contacts` | Fuzzy contact lookup by name, phone, JID, or LID. |\n| `resolve_jid` | Validate a phone number against WhatsApp and return its canonical JID. |\n| `edit_message` | Edit one of your own messages. |\n| `delete_message` | Delete a message in a chat. Defaults to deleting your own. |\n\n## Recipient formats\n\nTools that take a `to` argument accept any of:\n\n- A plain phone number with or without formatting: `5511987654321`, `+55 (11) 98765-4321`\n- A full JID: `5511987654321@s.whatsapp.net`\n- A LID (received from group/channel context): `123456789@lid`\n\nBrazilian mobile numbers are validated against WhatsApp via `onWhatsApp` to handle the optional 9th digit transparently.\n\n## Configuration\n\n| Env var | Default | Description |\n|---------|---------|-------------|\n| `WHATSAPP_MCP_DATA_DIR` | `~/.arvore-mcp/whatsapp` | Folder for auth state, SQLite DB, and QR PNG. |\n| `WHATSAPP_LOG_LEVEL` | `warn` | Pino log level for Baileys (`trace`, `debug`, `info`, `warn`, `error`). |\n\n## MCP config\n\nLocal development build (no publish required):\n\n```json\n{\n  \"mcpServers\": {\n    \"whatsapp\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/absolute/path/to/arvore-mcp-servers/packages/whatsapp/dist/index.js\"\n      ],\n      \"env\": {\n        \"WHATSAPP_LOG_LEVEL\": \"warn\"\n      },\n      \"autoApprove\": [\"*\"]\n    }\n  }\n}\n```\n\nOnce published:\n\n```json\n{\n  \"mcpServers\": {\n    \"whatsapp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@arvoretech/whatsapp-mcp\"],\n      \"env\": {\n        \"WHATSAPP_LOG_LEVEL\": \"warn\"\n      },\n      \"autoApprove\": [\"*\"]\n    }\n  }\n}\n```\n\n## Development\n\n```bash\npnpm install\npnpm --filter @arvoretech/whatsapp-mcp build\npnpm --filter @arvoretech/whatsapp-mcp dev\n```\n\n## Notes & gotchas\n\n- **Single connection only.** This MCP drives one WhatsApp account at a time and is intended for personal/agent use cases.\n- **Auth dir is per-machine.** Don't ship `~/.arvore-mcp/whatsapp/` — it contains your WhatsApp identity keys.\n- **Phone must stay online** occasionally for the multi-device session to stay healthy.\n- **Brazilian 9-digit gotcha:** Baileys sometimes returns a JID without the 9 even when you sent with it. The server uses `onWhatsApp` to resolve to the canonical JID before sending and before storing.\n- **Group messages are stored** but cannot be sent to yet (no `send_to_group` helper). Add one if needed.\n- **No incoming media auto-download.** `messages.upsert` events store metadata, but media is not pulled to disk. Add a `download_media` tool wired to Baileys' message store if you need it.\n- **Logout side effect:** `logout` clears local auth state and ends the socket. To fully revoke access, also unlink the device from WhatsApp on your phone.\n\n## Related\n\n- Drives one WhatsApp account from your local agent. For higher-volume server-side use cases, build a dedicated service.\n","readmeFilename":"README.md"}