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

1. Open the Viber Admin Panel
2. Create a new bot account (or select an existing one)
3. Copy the token from the bot's settings page
4. 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

License

MIT © Serhii Zghama