Viber Desktop MCP Server for Linux

A production-ready Model Context Protocol (MCP) server providing reliable, bidirectional automation for Viber Desktop on Linux.

Enables AI agents (such as Hermes Agent, Claude Desktop / Claude Code, and n8n automation pipelines) to search contacts, open chats, read conversation history, prepare verified drafts in any language, and send messages with strict operator oversight.

⚡ Highlights

• ⚡ Zero-OCR Instant Reading: Reads visible conversation history and composer state directly via Linux AT-SPI accessibility over D-Bus in milliseconds, with 100% exact character fidelity.

• 🌐 Full Multilingual & Unicode Support: Native clipboard injection (xclip + xdotool) guarantees flawless typing of Cyrillic characters (ї, є, ґ, І), emojis, and non-ASCII scripts.

• 📞 Universal Number Addressing: Switch to any phone number or saved contact instantly using Viber's native protocol launcher (viber://chat?number=...).

• 🔒 Race-Condition Safe: Built-in sequential execution lock (asyncio.Lock) ensures safe, serial execution on the single shared desktop GUI.

• 🛡️ Sandboxing & Daemon Compatibility: Transparently works inside isolated systemd services (e.g. PrivateTmp=true) via automated user-session runner delegation.

• 👥 Dynamic Address Book: Persistent contacts.json with fuzzy name/surname/alias lookup and dynamic contact saving (save_contact).

• 🛑 Strict Safety Gate: Draft creation (put_draft) is separated from sending (send_message), requiring explicit operator confirmation before dispatching.

Related MCP server: Linux System MCP Server

🛠️ System Requirements

• Operating System: Linux (Debian 12+, Ubuntu 22.04+, Arch, Fedora, etc.)

• Display Server: X11 (or XWayland / xrdp virtual display, e.g. :10)

• Viber Desktop: Official Viber Desktop for Linux (tested on Viber 27.3.x)

• Python: >= 3.11

• System Packages:

  sudo apt-get update && sudo apt-get install -y \
      xclip \
      xdotool \
      x11-utils \
      python3-dbus \
      python3-pil

📦 Installation

git clone https://github.com/vivajarvis777-dev/viber-mcp-linux.git
cd viber-mcp-linux

# Install using uv (recommended)
uv sync

# Or using standard venv + pip
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Copy the example contacts configuration:

cp contacts.example.json contacts.json

⚙️ Configuration & MCP Client Setup

1. Hermes Agent (~/.hermes/config.yaml)

Add the server to your Hermes MCP configuration:

mcp_servers:
  viber:
    command: /path/to/viber-mcp-linux/.venv/bin/python
    args:
      - /path/to/viber-mcp-linux/server.py
    timeout: 60
    connect_timeout: 15
    env:
      DISPLAY: :10.0
      XDG_SESSION_TYPE: x11
      XDG_RUNTIME_DIR: /run/user/1000
      DBUS_SESSION_BUS_ADDRESS: unix:path=/run/user/1000/bus
      VIBER_LAUNCHER: /path/to/launch-viber
    trust: full
    supports_parallel_tool_calls: false
    tools:
      include:
        - health
        - list_contacts
        - find_contact
        - save_contact
        - open_chat
        - read_open_chat
        - put_draft
        - send_message

2. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "viber": {
      "command": "/path/to/viber-mcp-linux/.venv/bin/python",
      "args": [
        "/path/to/viber-mcp-linux/server.py"
      ],
      "env": {
        "DISPLAY": ":0",
        "DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/1000/bus",
        "VIBER_LAUNCHER": "/opt/viber/Viber"
      }
    }
  }
}

3. n8n Workflow Automation

Configure an MCP Client Node in your n8n workflow connecting via stdio to /path/to/viber-mcp-linux/server.py. You can trigger automated Viber message drafting or notifications directly from webhooks, CRM updates, or incoming events.

🧰 Available MCP Tools

🏗️ Architecture & How It Works

flowchart TD
    Agent["AI Agent (Hermes / Claude / n8n)"] -->|MCP stdio| Server["server.py (FastMCP)"]
    Server --> Lock["asyncio.Lock (Sequential Safety)"]
    
    subgraph Viber_Linux_Automation ["Viber Desktop Linux Automation"]
        Lock --> Launcher["Launcher (viber://chat?number=...)"]
        Lock --> ATSPI["Direct D-Bus AT-SPI Reader"]
        Lock --> X11Input["X11 Clipboard & xdotool"]
        Lock --> VisualCheck["Dynamic Window Header Verification"]
    end
    
    Launcher -->|IPC| ViberApp["Viber Desktop (Qt / X11)"]
    X11Input -->|Ctrl+V / Return| ViberApp
    ViberApp -->|Accessible Tree| ATSPI
    ViberApp -->|Frame Buffer| VisualCheck

1. Direct D-Bus Accessibility (No OCR Latency)

Traditional GUI automation relies on screenshots and computer vision OCR, which are slow, error-prone, and cannot distinguish sender from recipient reliably. This MCP server communicates directly with the AT-SPI D-Bus accessibility registry (org.a11y.atspi.Accessible and org.a11y.atspi.Text). It reads chat history in under 50ms with 100% character precision.

2. Solving Linux Daemon Isolation (PrivateTmp=true)

When running as a background systemd service, agents often have PrivateTmp=true enabled. However, Viber Desktop creates its single-application IPC socket in the host's /tmp/Viber-0-3eb. This MCP server automatically detects mount namespace isolation and transparently executes the launcher command via systemd-run --user inside the user session, switching chats in ~1.2s without hanging.

3. Native Conversation Draft Preservation

Viber Desktop stores unsent composer text in memory per conversation. When switching between multiple contacts, drafts are preserved independently without leaking between chats.

🔒 Security & Safety Best Practices

1. Human-in-the-Loop Safeguard: The send_message tool requires an approval_token (defaulting to "CONFIRMED" only after explicit chat confirmation), ensuring the agent never sends unintended messages.

2. Privacy First: contacts.json and screenshot artifacts (private/) are ignored in .gitignore by default to prevent leaking personal phone numbers.

3. Execution Locking: The global async mutex prevents parallel commands from interleaving during clipboard operations or window switching.

📄 License

This project is licensed under the MIT License.