Viber MCP README

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

Account & Users

Webhooks

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:

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

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