Skip to content
Back to search

WhatsOps

WhatsOps — WhatsApp REST API + MCP server on Baileys (multi-number, OAuth 2.1, config page, EN/IT)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/emrgim/WhatsOps with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/emrgim/WhatsOps'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/emrgim--whatsops/badge.svg)](/listings/emrgim--whatsops)

HTML

<a href="/listings/emrgim--whatsops"><img src="/api/listings/emrgim--whatsops/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Download the installer for your system from the [latest release](https://github.com/emrgim/WhatsOps/releases/latest). Node.js is included: nothing else to install. Every installer sets WhatsOps up for your user, keeps it running in the background (it starts again at login and after a crash) and opens **http://127.0.0.1:8810** already signed in. New versions install by themselves (Settings → Updates).

| System | Installer | Install | |---|---|---| | macOS Intel | `WhatsOps-<version>-macos-x64.dmg` | Open it, drag **WhatsOps** to **Applications**, open WhatsOps. | | macOS Apple Silicon (M1–M4) | `WhatsOps-<version>-macos-arm64.dmg` | Same. | | Windows 10/11 (x64) | `WhatsOps-<version>-windows-x64-setup.exe` | Run it: no administrator rights needed. WhatsOps goes in the Start menu. | | Debian, Ubuntu, Mint… (x64, arm64) | `WhatsOps-<version>-linux-<x64\|arm64>.deb` | `sudo apt install ./WhatsOps-<version>-linux-x64.deb`, then open WhatsOps from the applications menu. | | Fedora, openSUSE… (x64, arm64) | `WhatsOps-<version>-linux-<x64\|arm64>.rpm` | `sudo dnf install ./WhatsOps-<version>-linux-x64.rpm`, then open WhatsOps from the applications menu. | | Any Linux (no root) | script | `curl -fsSL https://raw.githubusercontent.com/emrgim/WhatsOps/main/install/linux.sh \| bash` | | Omarchy | script | `curl -fsSL https://raw.githubusercontent.com/emrgim/WhatsOps/main/install/omarchy.sh \| bash` — opens as an Omarchy web app. |

Which Mac? Apple menu → About This Mac: *Chip Apple M…* → arm64, *Processor Intel* → x64. The `whatsops-…-runtime-….tar.gz` files in a release are not installers: WhatsOps downloads them when it updates itself.

The installers are not signed with paid Apple / Microsoft certificates, so the first time: - **macOS**: if it says it cannot check the app, right-click WhatsOps → **Open** → **Open** (macOS 15 and later: System Settings → Privacy & Security → **Open Anyway**). Once. - **Windows**: if SmartScreen says *Windows protected your PC*, click **More info** → **Run anyway**. Once.

Then go to **Numbers → Add number** and link the phone with the QR code or with a pairing code (WhatsApp → Linked devices → Link with phone number).

Where things are:

| | macOS | Windows | Linux | |---|---|---|---| | Data (database, sessions, media, logs) | `~/Library/Application Support/mcp-mrg-whatsops` | `%LOCALAPPDATA%\mcp-mrg-whatsops` | `~/.local/share/mcp-mrg-whatsops` | | Background service | LaunchAgent `im.mrg.whatsops` | sign-in entry `WhatsOps` (HKCU Run) | systemd user unit `whatsops.service` |

Uninstall: - **macOS**: `launchctl bootout gui/$(id -u)/im.mrg.whatsops; rm ~/Library/LaunchAgents/im.mrg.whatsops.plist`, then move WhatsOps to the Trash (delete the data folder too to remove everything). - **Windows**: Settings → Apps → WhatsOps → Uninstall. It stops WhatsOps and asks whether to delete your data. - **Linux**: `whatsops --uninstall` (packages) or `curl -fsSL https://raw.githubusercontent.com/emrgim/WhatsOps/main/install/linux.sh | bash -s -- --uninstall`; add `--purge` to delete the data. Then `sudo apt remove whatsops` / `sudo dnf remove whatsops` if you used a package.

The installers are built by GitHub Actions for every release ([`.github/workflows/packages.yml`](.github/workflows/packages.yml), [`packaging/build.mjs`](packaging/build.mjs)). Before a release gets them, each one is installed on its own system (macOS Intel and Apple Silicon, Windows, Ubuntu x64 and arm64), started, killed — it must come back by itself — and uninstalled.

From source (git)

Requirements: **Node.js 24+** and git.

git clone https://github.com/emrgim/WhatsOps.git
cd WhatsOps
npm ci
npm run build
npm start                      # listens on http://127.0.0.1:8810

First sign-in (no number is linked yet, so no WhatsApp code can be sent):

node dist/cli.js login-link    # prints a one-time admin URL, valid 30 minutes

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 184 lines · 3 findings marked
  1. <p align="center"><img src="assets/logo.svg" width="96" alt="WhatsOps"></p>
  2. # WhatsOps
  3. WhatsApp **REST API + MCP server** for your own numbers, built on [Baileys](https://baileys.wiki) v7 (WhatsApp Web linked device).
  4. One process holds one linked-device connection per number and exposes it three ways:
  5. - **MCP** (`/mcp`, Streamable HTTP) for AI agents: Claude, ChatGPT, Grok, Gemini, Cursor, Hermes… with OAuth 2.1 or API keys, plus a stdio proxy for stdio-only clients.
  6. - **REST API** (`/v1`) with OpenAPI docs at `/docs`, Server-Sent Events and signed webhooks.
  7. - **Config page** (`/`) to link numbers (QR code or phone-number pairing code) and edit their WhatsApp profile, connect plugins and MCP clients, create API keys, manage webhooks, choose the database and the appearance (Light / Dark / System), read the service log, send feedback and get updates.
  8. English and Italian: the config page follows the browser language, the server (MCP tool texts, errors) follows the operating system language.
  9. ## Features
  10. - Several WhatsApp numbers in one server, each with its own session; a default number for calls that do not name one.
  11. - Chats, messages, contacts and groups stored in SQL: **SQLite** by default, **PostgreSQL** or **MySQL/MariaDB** selectable from the config page (with optional copy of all data and automatic restart).
  12. - Full history import when a number is linked (optional), media download, search.
  13. - Send text, media (URL or base64), location, reactions; edit / delete own messages; mark as read. Idempotency keys, per-number rate limit, per-chat pause, optional recipient allow-list.
  14. - OAuth 2.1 (PKCE, dynamic client registration, static client ids) with 24 h access tokens and 90-day sliding refresh tokens; scoped API keys (`read`, `send`, `admin`) limited to chosen numbers.
  15. - Admin sign-in with a one-time code sent to the number's own "Message yourself" chat, a one-time login link, or a password.
  16. - Each number's id is its **phone number** and its name is its **WhatsApp profile name**, kept live. Name, info and photo can be edited from the config page, the API or MCP: the change is made on WhatsApp itself, so the two never differ.
  17. - **Feedback** (Settings → Feedback, or the `whatsops_feedback` MCP tool) opens an issue in this repository without any GitHub login: every installation signs with its own installation code (`WO-XXXX-XXXX`).
  18. - **Crash and malfunction reports**: crashes and errors are kept (scrubbed of numbers, names, keys and paths) and sent only if you choose: ask first (default), send automatically, or don't collect. The same problem becomes one issue.
  19. - **Auto-update**: a `git clone` installation checks this repository's releases every 5 minutes, installs a new version by itself (fetch, `npm ci`, build, restart) and goes back to the previous one if the new one does not start. Installations with local changes are never touched.
  20. - **Plugins** (Connectors → Plugins). First one: **Current RMS** — see below.
  21. - **Users with granular permissions** (Settings → Users). Besides the owner, users sign in with a code sent to their own WhatsApp number and see only what is enabled for them: by default nothing. Today a user can be given plugins; inside each plugin, its own permissions (Current RMS: only the records they own, or all; manage the plugin or not). Users never get numbers, messages, API keys, MCP or settings, and cannot authorize MCP clients.
  22. - Service log in **Settings → Log**, terminal style (`tail -f`): live, searchable, filterable by level, downloadable; every API change and MCP tool call is listed (never message bodies). Also kept as a rotating file in `<data>/logs/`.
  23. ## MCP tools
  24. `whatsapp_accounts`, `whatsapp_get_profile`, `whatsapp_update_profile`, `whatsops_feedback`, `currentrms_discussions`, `currentrms_set_sync`, `currentrms_users`, `currentrms_user_invite`, `whatsapp_list_chats`, `whatsapp_get_messages`, `whatsapp_search_messages`, `whatsapp_find_contact`, `whatsapp_check_number`, `whatsapp_list_groups`, `whatsapp_get_group`, `whatsapp_send_text`, `whatsapp_send_media`, `whatsapp_send_location`, `whatsapp_react`, `whatsapp_mark_read`, `whatsapp_edit_message`, `whatsapp_delete_message`, `whatsapp_download_media`.
  25. ## Install
  26. Download the installer for your system from the [latest release](https://github.com/emrgim/WhatsOps/releases/latest). Node.js is included: nothing else to install. Every installer sets WhatsOps up for your user, keeps it running in the background (it starts again at login and after a crash) and opens **http://127.0.0.1:8810** already signed in. New versions install by themselves (Settings → Updates).
  27. | System | Installer | Install |
  28. |---|---|---|
  29. | macOS Intel | `WhatsOps-<version>-macos-x64.dmg` | Open it, drag **WhatsOps** to **Applications**, open WhatsOps. |
  30. | macOS Apple Silicon (M1–M4) | `WhatsOps-<version>-macos-arm64.dmg` | Same. |
  31. | Windows 10/11 (x64) | `WhatsOps-<version>-windows-x64-setup.exe` | Run it: no administrator rights needed. WhatsOps goes in the Start menu. |
  32. | Debian, Ubuntu, Mint… (x64, arm64) | `WhatsOps-<version>-linux-<x64\|arm64>.deb` | `sudo apt install ./WhatsOps-<version>-linux-x64.deb`, then open WhatsOps from the applications menu. |
  33. | Fedora, openSUSE… (x64, arm64) | `WhatsOps-<version>-linux-<x64\|arm64>.rpm` | `sudo dnf install ./WhatsOps-<version>-linux-x64.rpm`, then open WhatsOps from the applications menu. |
  34. | Any Linux (no root) | script | `curl -fsSL https://raw.githubusercontent.com/emrgim/WhatsOps/main/install/linux.sh \| bash` |
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 46 on GitHub
  35. | Omarchy | script | `curl -fsSL https://raw.githubusercontent.com/emrgim/WhatsOps/main/install/omarchy.sh \| bash` — opens as an Omarchy web app. |
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 47 on GitHub
  36. Which Mac? Apple menu → About This Mac: *Chip Apple M…* → arm64, *Processor Intel* → x64. The `whatsops-…-runtime-….tar.gz` files in a release are not installers: WhatsOps downloads them when it updates itself.
  37. The installers are not signed with paid Apple / Microsoft certificates, so the first time:
  38. - **macOS**: if it says it cannot check the app, right-click WhatsOps → **Open** → **Open** (macOS 15 and later: System Settings → Privacy & Security → **Open Anyway**). Once.
  39. - **Windows**: if SmartScreen says *Windows protected your PC*, click **More info** → **Run anyway**. Once.
  40. Then go to **Numbers → Add number** and link the phone with the QR code or with a pairing code (WhatsApp → Linked devices → Link with phone number).
  41. Where things are:
  42. | | macOS | Windows | Linux |
  43. |---|---|---|---|
  44. | Data (database, sessions, media, logs) | `~/Library/Application Support/mcp-mrg-whatsops` | `%LOCALAPPDATA%\mcp-mrg-whatsops` | `~/.local/share/mcp-mrg-whatsops` |
  45. | Background service | LaunchAgent `im.mrg.whatsops` | sign-in entry `WhatsOps` (HKCU Run) | systemd user unit `whatsops.service` |
  46. Uninstall:
  47. - **macOS**: `launchctl bootout gui/$(id -u)/im.mrg.whatsops; rm ~/Library/LaunchAgents/im.mrg.whatsops.plist`, then move WhatsOps to the Trash (delete the data folder too to remove everything).
  48. - **Windows**: Settings → Apps → WhatsOps → Uninstall. It stops WhatsOps and asks whether to delete your data.
  49. - **Linux**: `whatsops --uninstall` (packages) or `curl -fsSL https://raw.githubusercontent.com/emrgim/WhatsOps/main/install/linux.sh | bash -s -- --uninstall`; add `--purge` to delete the data. Then `sudo apt remove whatsops` / `sudo dnf remove whatsops` if you used a package.
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 67 on GitHub
  50. The installers are built by GitHub Actions for every release ([`.github/workflows/packages.yml`](.github/workflows/packages.yml), [`packaging/build.mjs`](packaging/build.mjs)). Before a release gets them, each one is installed on its own system (macOS Intel and Apple Silicon, Windows, Ubuntu x64 and arm64), started, killed — it must come back by itself — and uninstalled.
  51. ### From source (git)
  52. Requirements: **Node.js 24+** and git.
  53. ```bash
  54. git clone https://github.com/emrgim/WhatsOps.git
  55. cd WhatsOps
  56. npm ci
  57. npm run build
  58. npm start # listens on http://127.0.0.1:8810
  59. ```
  60. First sign-in (no number is linked yet, so no WhatsApp code can be sent):
  61. ```bash
  62. node dist/cli.js login-link # prints a one-time admin URL, valid 30 minutes
  63. ```
  64. Open it, go to **Numbers → Add number**, and link the phone with the QR code or with a pairing code (WhatsApp → Linked devices → Link with phone number).
  65. Run it as a service: `deploy/mcp-mrg-whatsops.service` is a systemd user unit (adjust the paths, see the comments inside). Auto-update restarts the service by itself, so keep a service manager with automatic restart (systemd `Restart=always`, launchd `KeepAlive`).
  66. ### Expose it
  67. WhatsOps listens on loopback only. Put it behind a reverse proxy or tunnel (Caddy, nginx, Cloudflare Tunnel…) with HTTPS and set the public URL (`WA_PUBLIC_URL` or Settings → General). OAuth and the MCP connectors need the public HTTPS URL.
  68. ## Connect
  69. The config page, **Connectors**, lists plugins and MCP clients as tiles (Cursor, Claude, ChatGPT, Grok, Grok Bot, Hermes, Gemini, any other MCP client); open a tile for its ready-to-paste settings.
  70. - **OAuth clients** (Claude, ChatGPT, Gemini, Grok): add a remote MCP connector with `https://<your-host>/mcp`; the client registers itself and you approve it in the browser.
  71. - **API key clients** (Hermes, scripts): create a key in **Connectors → API** and send `Authorization: Bearer wam_…` (or `?token=wam_…`).
  72. - **stdio-only clients**: `WA_MCP_URL=https://<your-host>/mcp WA_API_KEY=wam_… node dist/cli.js stdio`.
  73. REST example:
  74. ```bash
  75. curl -H "Authorization: Bearer wam_…" \
  76. -H "Content-Type: application/json" \
  77. -d '{"to":"+15551234567","text":"Hello","idempotencyKey":"hello-1"}' \
  78. http://127.0.0.1:8810/v1/messages/text
  79. ```
  80. The full API vocabulary is in **Connectors → API** and at `/docs`.
  81. ### Webhooks
  82. Events: `message.received`, `message.sent`, `message.update`, `connection.update`, `history.sync`, `chat.update`, `profile.update` (or `*`). Each delivery is a JSON `POST` signed with
  83. `X-WA-Signature: sha256=HMAC(secret, X-WA-Timestamp + "." + body)` and retried up to 5 times (1 min → 12 h). Live events are also available as SSE at `/v1/events`.
  84. ## CLI
  85. ```
  86. node dist/cli.js serve start the server (same as npm start)
  87. node dist/cli.js stdio stdio MCP proxy (env WA_MCP_URL, WA_API_KEY, WA_LANG)
  88. node dist/cli.js login-link [--minutes 30] one-time admin login URL
  89. node dist/cli.js key --name N --scopes read,send[,admin] [--accounts id1,id2]
  90. node dist/cli.js db show | db set <sqlite:///path|postgres://…|mysql://…>
  91. node dist/cli.js status
  92. ```
  93. ## Plugin: Current RMS
  94. Links the discussions of [Current RMS](https://www.current-rms.com) (OnRent Events) to a WhatsApp number. Connectors → Plugins → Current RMS:
  95. 1. **Connection**: your subdomain (`yourcompany` from `yourcompany.current-rms.com`) and an API key (System Setup → Integrations → API). The key is stored on the server and never shown again.
  96. 2. **Settings**:
  97. - **WhatsApp number** that owns the groups.
  98. - **Structure on WhatsApp**: *Single groups* — separate groups (one per record, one per discussion), fully isolated, nobody sees the other discussions; or *Community per record* — one Community per record (opportunity, project, contact…) with the record group and a group per discussion: messages stay sealed in each group and new members need approval, but Community members can see the names of all its groups.
  99. - **What to sync**, per kind of record (opportunities, projects, products, services, contacts, invoices, activities, quarantines, purchase orders), on three levels:
  100. | Level | What happens | Calls to Current RMS |
  101. |---|---|---|
  102. | **Group for each new record** | a record is created (e.g. a new opportunity) → WhatsOps creates its WhatsApp group | 1 per kind at every check (webhooks: at once) + 2–3 per group |
  103. | **Group for each new discussion** | a discussion is created on one of these records → a group for that discussion | 1 at every check for all kinds + 2–3 per group |
  104. | **Messages** | comments ⇄ WhatsApp messages in the discussion groups, both ways; off = the groups are only for chatting | 1 per WhatsApp message + 1 every 100 groups at every check |
  105. Only records and discussions created after a level is switched on get a group by themselves (existing ones: the switches in the list). Automatic groups are created one at a time, 45 s apart, at most 50 a day; a group switched off by hand is never switched on again by itself. Switching messages on later starts from the current comments: old ones are not posted.
  106. - **Contacts custom field** that holds the WhatsApp number: only participants with a number there are added.
  107. - People who can't be added (privacy settings) get the **invite link** privately (can be turned off).
  108. 3. **Discussions**: listed by record, with participants and replies. Each record has a *Record group* switch (its own WhatsApp group). Turning a discussion on creates the WhatsApp group (closed: only admins add people and change settings, approval on) and adds the participants; when messages are synced for that kind of record it also posts the whole discussion grouped by day, then mirrors both ways: a new comment in Current RMS → a message in the group (`*Name*` + text); a message in the group → a comment in the discussion (as the matching contact when possible, otherwise `Name (WhatsApp): text`).
  109. 4. **Instant updates**: turn webhooks on in Current RMS (System Setup → Company Information), then *Register webhooks*: WhatsOps registers only the events the chosen levels need (`<record>_create`, `<record>_discuss`, `discussion_comment`) and updates them when the levels change. WhatsOps must have a public HTTPS address (`WA_PUBLIC_URL`). Without webhooks, Current RMS is checked every 2, 5, 15 or 30 minutes.
  110. **Admins.** The main number (the default one unless chosen in the plugin) creates every group and Community, so it is their creator. Two more admins are added and promoted:
  111. - the **backup number** (another WhatsOps number): admin everywhere; while the main number is offline the sync goes on from the backup;
  112. - the **owner of the record** in Current RMS (e.g. whoever owns the opportunity), when they have a WhatsApp number — confirmed through their personal invite link, or in the contacts custom field. If the owner changes in Current RMS, the new owner is added as admin.
  113. **Current RMS users** (plugin → Users): send each one their personal invite link (valid 14 days): they type their WhatsApp number, receive a code on WhatsApp and confirm. From the same list the owner decides who signs in to WhatsOps, and whether they see only the records they own or all, and whether they manage the plugin. A user limited to their own records sees only those discussions and can switch only their sync.
  114. Groups are created one at a time with a pause between them, so WhatsApp does not see a burst. API calls stay under Current RMS' limit of 60 per minute. The same is available from the API (`/v1/plugins/currentrms/…`, levels in `PUT …/config` → `levels`, record groups in `PUT …/records/{type}/{id}`) and MCP (`currentrms_discussions`, `currentrms_set_sync`, `currentrms_record_group`).
  115. ## Configuration
  116. Everything is configured from the config page. Optional environment variables are listed in [`.env.example`](.env.example) (`WA_HOST`, `WA_PORT`, `WA_PUBLIC_URL`, `WA_DATA_DIR`, `WA_DB_URL`, `WA_LANG`, `WA_LOG_LEVEL`, `WA_THEME`).
  117. Forks: point feedback, reports and updates to your own repository with `WA_FEEDBACK_REPO=owner/repo`, `WA_FEEDBACK_TOKEN` (a fine-grained token with only *Issues: read & write* on that repository) and `WA_UPDATE_REPO`; `WA_UPDATE_INTERVAL_MIN` changes the update check interval.
  118. Licenses: WhatsOps is free. A [Polar](https://polar.sh) license check is built in but off; it turns on only when a Polar organization is set (`WA_POLAR_ORG_ID`).
  119. Data (database, media, backups) lives in `~/.local/share/mcp-mrg-whatsops/` (macOS: `~/Library/Application Support/mcp-mrg-whatsops/`), never in the repository.
  120. ## Notes
  121. - WhatsOps is an unofficial WhatsApp Web client. Use it with your own numbers and follow WhatsApp's terms.
  122. - WhatsApp unlinks linked devices when the main phone stays offline for more than 14 days.
  123. - One server per number: do not link the same device to two programs at once.
  124. - The key in `src/issues-key.ts` can only open issues in this repository and nothing else; it is scrambled only so that secret scanners don't revoke it.
  125. ## Development
  126. ```bash
  127. npm run typecheck
  128. npm test
  129. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.