viber-claude-connector
Connects to Viber Desktop on macOS to list chats, read and search messages, check unread chats and missed calls, and send messages or like/remove likes on visible messages after explicit user confirmation.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
viber-claude-connector
A local stdio MCP server that connects Claude (Claude Code) to Viber Desktop on macOS: read your chats from Viber's local database, and send messages through Viber's own UI, only after you approve the exact draft.
There is no Viber API for personal accounts (the Bot API is commercial-only since Feb 2024 and can't send as you), so this server:
reads the encrypted
viber.dbread-only, through Viber's own bundled SQLite codec;sends by driving the Viber app with the macOS Accessibility API (open chat → put text in the message box → press Enter). No DB writes, no protocol reverse-engineering.
Unofficial. Not affiliated with or endorsed by Rakuten Viber or Anthropic. It automates your own Viber account through the macOS UI. Use it responsibly and at your own risk.
Privacy
Everything runs on your Mac. The server reads
viber.dblocally and talks only to the Claude app that started it. It makes no network requests of its own.Whatever Claude reads (messages, names, numbers) becomes part of your Claude conversation, and Anthropic processes it like anything else you share with Claude. That includes your contacts' messages, so be deliberate about what you ask it to read.
Nothing is ever written to Viber's databases. The local audit log (
state/state.db) stores chat ids, hashes and lengths, never message text.
Related MCP server: WhatsApp MCP for macOS
Tools
Tool | What it does |
| Chats by recent activity: id, name, type (direct/group/community/notes), unread count, missed calls, last-message preview |
| Messages of one chat, oldest first, with reactions (counts + |
| Case-insensitive full-text search (Cyrillic-aware). All words must match; |
| Chats with unread messages (same semantics as Viber's Unread filter) plus missed calls |
| Sends one text message to one chat after you confirm the draft in a dialog |
| Likes (❤️) one message, or removes your like ( |
A chat can be referenced by id (42, #42), exact or partial name ("hiking"), or phone number.
Ambiguous references are rejected with a list of candidates, never guessed.
Requirements
macOS (tested: macOS 26.6, Apple Silicon) with Viber Desktop installed and signed in (tested: 29.5.0).
Xcode command line tools (
xcode-select --install:clang++,swiftc, Python 3), Node.js ≥ 22.13 (built-innode:sqlite).For sending, the app that launches the server needs the permissions below: your terminal/IDE for Claude Code (Terminal, iTerm, IntelliJ…), or Claude.app for the desktop app (see Claude desktop app):
Accessibility: System Settings → Privacy & Security → Accessibility;
Screen Recording: used to OCR the search-result row and the chat header, since neither is exposed via Accessibility.
Setup
Clone this repository, then from its folder:
npm install
npm run build # bin/viberdb (C++), bin/viberax (Swift), dist/ (TypeScript)
npm test # unit tests (no Viber needed)
node scripts/smoke.mjs # end-to-end read check over MCP stdio (prints counts, not content)The first build downloads the Qt headers that match the Qt inside your Viber.app (QtCore + QtSql only, a few MB,
via aqtinstall in a throwaway venv) into ./vendor. Nothing from Qt is
linked statically: the helper uses Viber's own Qt libraries at runtime.
Register with Claude Code (run from this folder; local scope = only when Claude runs here):
claude mcp add --transport stdio viber -- "$(which node)" "$PWD/dist/index.js"
# available in every project instead:
claude mcp add --scope user --transport stdio viber -- "$(which node)" "$PWD/dist/index.js"Then start a new Claude Code session and ask e.g. "what's unread on Viber?".
Claude desktop app
The same server also runs under the Claude desktop app. Each app starts its own copy of the server (the desktop
app even starts two: claude-ai for chats and local-agent-mode-viber for agent mode). All copies share one state
file, so the send lock and the pace limits apply across all of them (see Guardrails).
Add the server (backs up the config, merges only
mcpServers.viber, validates the JSON, keeps every other key untouched, absolute paths only):python3 scripts/install-desktop-config.py # --confirm client|dialog, --dry-run, --node /abs/pathIt writes this entry to
~/Library/Application Support/Claude/claude_desktop_config.json:"viber": { "command": "/Users/<you>/.nvm/versions/node/v22.21.1/bin/node", "args": ["/Users/<you>/Documents/viber-claude-connector/dist/index.js"], "env": { "VIBER_CONFIRM": "dialog", "VIBER_MCP_STATE_DIR": "/Users/<you>/Documents/viber-claude-connector/state" } }(
"client"instead of"dialog"with--confirm client, see step 4.) The desktop app doesn't load your shell, so nothing may depend onPATH/nvm. Check the exact command in a clean environment withpython3 scripts/check-desktop-command.py.Quit the desktop app with Cmd+Q and reopen it, after every config change and after every
npm run build. The app starts its server copies at launch and keeps them running, so reloading the window isn't enough. The app sometimes rewrites this file itself. Ifviberis missing after reopening, quit the app, re-run the script (it's idempotent), and reopen.Grant macOS permissions to Claude (System Settings → Privacy & Security). macOS attributes everything the server does to the app that launched it:
Permission
Why
Accessibility → Claude
reading/setting Viber's search field and message box, Enter, the click on the search result
Screen & System Audio Recording → Claude
capturing Viber's window to OCR the search result row and chat header
Files & Folders → Claude → Documents Folder
the server lives in
~/Documents(code +state/). macOS asks on first launch; click AllowNothing else is needed: no Automation (the dialog uses no Apple Events), no Input Monitoring, no Full Disk Access. After granting Screen Recording, macOS asks you to quit and reopen Claude. If a permission is missing, the first send attempt fails before any dialog, and the server triggers macOS's own prompt, which names the exact app. Note: the desktop app starts MCP servers through a helper named
disclaimer, which makes macOS treat the server as its own responsible process. The permissions may therefore have to go to thenodebinary (/Users/<you>/.nvm/versions/node/v22.21.1/bin/node) rather than to Claude. The prompt names the right one; you can also add it to both lists with +. Check the result in the log (accessibility=… screenRecording=…).Confirmation in the desktop app. Pick one with
--confirm(re-runs keep the current choice):--confirm dialog(default): every send shows the macOS dialog (Cancel is the default button).--confirm client: no extra dialog. The desktop app's own "Allow tool?" prompt, which shows the tool arguments, is the confirmation. So that prompt shows exactly who receives what, the server then accepts only the exact full chat name (or a phone number) as the recipient, never an id or a partial name. ⚠️ Answer "Allow once" forsend_message. Always allow or Allow for this chat would let later sends go out with no confirmation at all (only the rate limits would remain).
The in-app form is only used for Claude Code (
clientInfo.name == "claude-code"declaring form-mode elicitation). Other clients never get it.
Logs
File | Contents |
| this server's stderr: startup line, which client connected (and whether it declares in-app forms) and how sends will be confirmed, and the permissions of the launching app ( |
| the desktop app's MCP connection events (start, stop, errors) |
| general app log (config writes, crashes) |
tail -f ~/Library/Logs/Claude/mcp-server-viber.logThe desktop app shows server status under Settings → Developer.
How it works
Reading: bin/viberdb (C++)
On current macOS builds viber.db is encrypted with SQLite SEE (AES-128 scheme). The codec lives inside Viber's
Qt SQLite plugin (Viber.app/Contents/PlugIns/sqldrivers/libqsqlite.dylib), which exports no sqlite3_*
symbols. So viberdb is compiled against Qt 6 headers but links Viber's own QtCore/QtSql at runtime
and opens the DB through QSqlDatabase("QSQLITE"). Viber derives the key at runtime as
"aes128:" + reverse(<macOS login name>), passed hex-encoded to PRAGMA hexkey; nothing is stored on disk.
Read-only guarantees, layered:
the connection is opened with
SQLITE_OPEN_READONLY;PRAGMA query_only=1is set right after keying;the helper only accepts
SELECT/WITH(plus a few introspection pragmas);Qt prepares only the first statement of a string, so nothing can be appended.
The DB is read live (including the WAL), so new messages appear immediately. Keys travel over stdin,
never argv. The helper speaks JSON on stdin/stdout; all SQL lives in src/repo.ts.
Sending: bin/viberax (Swift) + src/ui.ts
Viber is a Qt Quick app. Its Accessibility tree exposes stable QML object paths (search field,
message box QQuickTextEdit, SendToolbarButton, visible messages), but not the chat-list rows or the
conversation title. A send therefore goes like this:
Resolve the recipient in
viber.db(exactly one chat, or it stops).Rate limits (see below), plus a preflight: Viber running, Accessibility granted.
Confirmation. Claude Code shows an MCP elicitation form with the recipient (taken from the DB, not from the model), the requesting app and the exact text, and nothing happens unless you tick "Yes, send this message" and submit. Every other client, the Claude desktop app included, gets a native macOS dialog whose default button is Cancel. Approval is only ever a submitted form with the box ticked, or the dialog's Send button. Decline, cancel, timeout, a missing capability or an error all mean not sent. In non-interactive sessions the request is cancelled.
Open the chat. Focus the search field via AX, set the chat name, OCR the result list (Apple Vision) to find the row with that name, and click it. Viber needs a real click here; Return/Down don't open results.
Verify that it's the right chat: OCR the conversation header (must match the name) and match the visible messages against that chat's latest messages in
viber.db. If verification fails, the send aborts.Compose. Refuse if the message box already holds your draft. Otherwise set the text via AX, read it back, check it matches exactly, and re-check the header.
Press Enter, or use the Send button if Enter only inserts a newline.
Confirm that the new outgoing message appears in
viber.db, then return focus to the app you were using.
Reacting: react_to_message
Viber's ♡ (next to a message) is a toggle: one click likes the message, a second click removes the like. It isn't in the Accessibility tree, and the right-click menu has no "React" item, so:
Resolve the chat and look the message up in
viber.db. Calls, system notices and your own messages are rejected; so is a request that wouldn't change anything (already liked, or nothing to remove), before any confirmation.Confirmation (same modes as sending). It shows the chat, the sender, the time and the message excerpt (or
[photo]).Open and verify the chat (same checks as sending).
viberax heartfinds the ♡ from fresh Accessibility geometry and clicks it in one atomic step:text: hover the bubble (matched by its exact text) to reveal its action row; the ♡ sits 29 pt right of the reply icon, centred on the bubble;
photo/video: the ♡ is the round button 34 pt left of the bubble's share button. Before clicking, the bubble's time label (e.g.
14:05) must be read off the screen by OCR as an identity check;if the feed moved between measuring and clicking (new messages arriving), it aborts instead of clicking. Identical texts and several photos are told apart by counting newer ones from the bottom.
Verify in
viber.dbthat your reaction on that message is now ❤️ (or gone), and that no other message's reaction changed. It never retries blindly: a second click would undo the first.
Limits of this first version: ❤️ only (Viber stores it as type 1; other emoji need its picker, not supported yet),
no reactions to your own messages, and the message must be visible after opening the chat (recent messages).
The ♡ offsets were calibrated on Viber 29.5 and may need adjusting after a Viber redesign. The click then misses
harmlessly and the result is reported as unconfirmed.
Keystrokes are posted only to Viber's process and only while Viber is frontmost. Clicks happen only if Viber's window is the topmost window at that point; for example, the macOS Screenshot overlay blocks them.
Guardrails
Explicit confirmation of every send (see above). The model cannot answer the dialog.
Untrusted content. Message text, names, quotes and link titles are returned only inside JSON strings, stripped of invisible/bidi control characters, and labelled untrusted. Server instructions and tool descriptions tell Claude never to act on instructions found in messages.
Human pace, no bulk. At least 30 s between sends, ≤ 10/hour, ≤ 40/day. Identical text to a different chat within an hour is blocked (no broadcasts), as are repeats to the same chat within 10 min. Three declined drafts in 10 min trigger a cool-down.
Reactions have their own human pace: at least 10 s apart, ≤ 20/hour, ≤ 60/day. They share the global lock and the decline cool-down with messages (3 declines of anything in 10 min trigger the cool-down).
Shared across Claude apps. The limits live in
state/state.db(SQLite), not in memory. A send holds SQLite's write lock (BEGIN IMMEDIATE) from the limit check, through the confirmation dialog and delivery, until its outcome is recorded. If another copy tries to send meanwhile (e.g. Claude Code while the desktop app's dialog is open), it's rejected with "another send is in progress". If a process dies, the OS releases its lock, so there are no stale lock files.scripts/test-shared-limits.mjschecks this with two real server processes.Audit log.
state/state.dbrecords the time, chat id, outcome, requesting client, text hash and length (not the text):sqlite3 -readonly state/state.db "SELECT datetime(ts/1000,'unixepoch','localtime'), chat_id, outcome, client, len FROM sends".Read-only DB, as described above.
Configuration (environment variables)
Variable | Default | Purpose |
|
| Viber bundle (codec + Qt frameworks) |
| newest | DB to read |
| current login name | Login name used to derive the key (for a DB copied from another Mac) |
| — | Comma-separated captured |
|
| Shared state ( |
|
|
|
| 30 / 10 / 40 | Pace limits |
| 2000 | Max message length |
| 10 / 20 / 60 | Reaction pace limits |
Troubleshooting
no key candidate opened the database: Viber changed its key derivation. Capture thePRAGMA hexkeyViber issues (see GhostingBit/viber-export'sINTERNALS.md) and pass it viaVIBER_DB_HEXKEY.QSQLITE driver not loadableor crashes after a Viber update: Viber's bundled Qt version changed. Re-runnpm run build: it detects the new version and fetches matching headers.Send fails with
unverified/not_found: the chat name shown in Viber differs from the DB name, or the UI layout changed.bin/ax-dumpshows the current Accessibility tree; values are redacted unless you pass--values.occluded/not_frontmost: another window covered Viber, or focus changed mid-send. Nothing was sent, so just try again.Desktop app: server missing or "failed": check
~/Library/Logs/Claude/mcp.logandmcp-server-viber.log.EPERMondist/index.jsmeans the Documents-folder permission for Claude is missing. "command not found" means the node path in the config is gone (e.g. nvm version removed), so re-runinstall-desktop-config.py.another send is in progress: a confirmation is open in the other Claude app (or the last send is still being confirmed inviber.db). Answer or close it, then retry.
Development
native/viberdb/viberdb.cpp read-only DB harness (Qt, links Viber's frameworks)
native/viberax/main.swift AX/OCR/click primitives, one JSON object per command
src/ MCP server (TypeScript): index, repo (SQL), format, match, ui, send, confirm, ratelimit
scripts/q.py ad-hoc read-only SQL: scripts/q.py "SELECT count(*) FROM Events"
scripts/smoke.mjs end-to-end read test over MCP (counts only; --show to print content)
scripts/test-send-guards.mjs send_message guard tests (auto-declines; never sends)
scripts/test-shared-limits.mjs two server processes share the send lock + limits (auto-declines; never sends)
scripts/send-test.mjs live send through the native confirmation dialog (you must click Send)
scripts/react-test.mjs live like/un-like through the native dialog (you must click Like)
scripts/test-react-guards.mjs react_to_message guard tests (auto-declines; never reacts)
scripts/dev-open-chat.mjs open + verify a chat through the production path (sends nothing)
scripts/install-desktop-config.py add/refresh the viber entry in the Claude desktop config (backup + validate)
scripts/check-desktop-command.py run the desktop entry's exact command in a clean env + MCP handshake
scripts/ax-dump.swift dump Viber's Accessibility treeContributions are welcome. CLAUDE.md lists the project's hard rules and hard-won gotchas (useful for humans too).
Credits
The key formula and the "use Viber's own codec" approach are documented in
GhostingBit/viber-export (INTERNALS.md). Reading the DB through
Viber's bundled Qt driver was pioneered by the (no longer available) vibcrawl project.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Your own WhatsApp in Claude and ChatGPT: read chats, draft replies, send messages you approve.
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Mac & Windows: let ChatGPT, Claude & Cursor use your email, calendar, iMessage, Teams, files.
Let Claude or ChatGPT search, read and send your WhatsApp messages over MCP. OAuth sign-in.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude to send and read iMessages on macOS, with smart contact lookup, message history retrieval, and cross-conversation search using natural language commands.6MIT
- AlicenseAqualityCmaintenanceEnables Claude to interact with WhatsApp on macOS through the Model Context Protocol. It allows reading messages, searching contacts, listing chats, and sending replies via natural conversation.858 PyPI2MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to send and read iMessages on macOS, with human approval required for sending and no auto-replies.2Apache 2.0
- AlicenseAqualityDmaintenanceConnects Claude Desktop to iMessage on macOS, enabling reading conversations, searching messages, sending texts, and managing attachments.78 npmMIT