README.md

May 25, 2026 · View on GitHub

Viber
viber-mcp

Model Context Protocol server for the Viber Bot API

The first MCP server for Viber. Connect any MCP-compatible client -- Claude Desktop, Claude Code, Cursor, Windsurf, and others -- to the Viber Bot REST API and control your Viber bot through natural language.

Viber has over 1 billion registered users, particularly strong in Ukraine, Eastern Europe, Greece, and Southeast Asia. This server gives AI assistants full access to the bot API: send messages, media, files, broadcast to groups, manage webhooks, and query user data.

How it works

┌──────────────────────┐         stdio           ┌──────────────────────┐
│                      │  ◄───────────────────►  │                      │
│   MCP Client         │    JSON-RPC over        │   viber-mcp          │
│                      │    stdin/stdout         │                      │
│   - Claude Desktop   │                         │   13 tools           │
│   - Claude Code      │                         │   Zod validation     │──── HTTPS ───►  Viber API
│   - Cursor           │                         │   Error handling     │                 chatapi.viber.com
│   - Any MCP client   │                         │   Typed responses    │
│                      │                         │                      │
└──────────────────────┘                         └──────────────────────┘

Quick start

Try it instantly -- no install required:

VIBER_AUTH_TOKEN=your-token npx @serhii.zghama/viber-mcp

Or install globally:

npm install -g @serhii.zghama/viber-mcp

Setup

Claude Desktop

Add to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "viber": {
      "command": "npx",
      "args": ["-y", "@serhii.zghama/viber-mcp"],
      "env": {
        "VIBER_AUTH_TOKEN": "your-bot-token-here",
        "VIBER_SENDER_NAME": "MyBot"
      }
    }
  }
}

Windows note: Replace "command": "npx" with "command": "cmd" and "args" with ["/c", "npx", "-y", "@serhii.zghama/viber-mcp"].

Restart Claude Desktop. The Viber tools will appear in the tools menu.

Claude Code

claude mcp add viber-mcp -e VIBER_AUTH_TOKEN=your-bot-token-here -- npx -y @serhii.zghama/viber-mcp

Cursor

Open Settings > MCP Servers, click + Add, and paste:

{
  "viber": {
    "command": "npx",
    "args": ["-y", "@serhii.zghama/viber-mcp"],
    "env": {
      "VIBER_AUTH_TOKEN": "your-bot-token-here"
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "viber": {
      "command": "npx",
      "args": ["-y", "@serhii.zghama/viber-mcp"],
      "env": {
        "VIBER_AUTH_TOKEN": "your-bot-token-here"
      }
    }
  }
}

Tools

13 tools covering the full Viber Bot API surface:

Messaging

Tool	Description	Key parameters
`send_message`	Send a text message	`receiver`, `text` (up to 7000 chars)
`send_picture`	Send an image with optional caption	`receiver`, `media` (URL), `text` (caption)
`send_video`	Send a video	`receiver`, `media` (URL), `size` (bytes)
`send_file`	Send a file attachment	`receiver`, `media` (URL), `size`, `file_name`
`send_url`	Send a clickable link	`receiver`, `media` (URL, max 2000 chars)
`send_location`	Send GPS coordinates	`receiver`, `latitude`, `longitude`
`send_contact`	Send a contact card	`receiver`, `name`, `phone_number`
`broadcast_message`	Broadcast to up to 300 users	`receivers` (array), `text`

Account & Users

Tool	Description	Key parameters
`get_account_info`	Get bot profile and subscriber count	none
`get_user_details`	Fetch user profile (rate-limited: 2/12h per user)	`id`
`get_online`	Check online status of up to 100 users	`ids` (array)

Webhooks

Tool	Description	Key parameters
`set_webhook`	Register a webhook URL	`url`, `event_types` (optional)
`remove_webhook`	Disable the current webhook	none

All tools validate inputs with Zod schemas before calling the Viber API. On errors, tools return human-readable messages with isError: true so the AI can decide how to proceed.

Full schema details and examples in docs/API_REFERENCE.md.

Configuration

Environment variables, read once at startup:

Variable	Required	Default	Description
`VIBER_AUTH_TOKEN`	yes	--	Bot auth token from the Viber Admin Panel
`VIBER_SENDER_NAME`	no	`Bot`	Default sender display name (max 28 chars)
`VIBER_SENDER_AVATAR`	no	--	Default sender avatar URL
`VIBER_BASE_URL`	no	`https://chatapi.viber.com/pa`	API base URL override
`VIBER_REQUEST_TIMEOUT_MS`	no	`15000`	Per-request timeout in milliseconds

Getting a Viber bot token

Open the Viber Admin Panel
Create a new bot account (or select an existing one)
Copy the token from the bot's settings page
Set it as VIBER_AUTH_TOKEN in your MCP client config

Note: Since February 2024, new Viber bot accounts may require commercial onboarding through Viber partners. Existing bot tokens continue to work.

Development

git clone https://github.com/serhiizghama/viber-mcp.git
cd viber-mcp
pnpm install

Command	Description
`pnpm build`	Build with tsup (ESM, Node 20+)
`pnpm dev`	Build with file watching
`pnpm typecheck`	Run TypeScript strict checks
`pnpm test`	Run vitest (36 tests)

Project structure

src/
  index.ts           -- Entrypoint: config -> client -> server -> stdio
  config.ts          -- Environment variable parsing
  errors.ts          -- ViberApiError class
  server.ts          -- MCP server builder with tool registration
  viber/
    client.ts        -- Typed HTTP client for the Viber REST API
    types.ts         -- Request/response TypeScript interfaces
  tools/
    send-message.ts  -- One file per tool, Zod schema + handler
    ...              -- 12 more tool files
tests/
  viber-client.test.ts   -- Client unit tests (mocked fetch)
  server.test.ts         -- Integration test (spawns server, queries tools/list)
  tools/*.test.ts        -- Per-tool success + error path tests

Architecture decisions

Zero console.log -- stdout is the MCP protocol channel; only console.error for diagnostics
Native fetch -- no axios/node-fetch; minimal runtime dependencies
No retries -- Viber REST calls are user-driven via MCP; silent retries would hide real problems from the AI
Zod validation -- every tool input is validated before reaching the Viber API
Tools never throw -- errors are caught and returned as { isError: true } so the AI can handle them gracefully

Roadmap

Future work -- contributions welcome:

Rich media / carousels -- send_rich_media tool with carousel layout
Keyboards -- interactive button keyboards on messages
Webhook receiver -- sibling package for incoming events via HTTP
Stickers -- send_sticker tool
HTTP transport -- Streamable HTTP for remote MCP deployments