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