viber-mcp
Model Context Protocol server for the Viber Bot API
---
The first MCP server for [Viber](https://www.viber.com/). Connect any MCP-compatible client -- Claude Desktop, Claude Code, Cursor, Windsurf, and others -- to the [Viber Bot REST API](https://developers.viber.com/docs/api/rest-bot-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:
```bash
VIBER_AUTH_TOKEN=your-token npx @serhii.zghama/viber-mcp
```
Or install globally:
```bash
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`
```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
```bash
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:
```json
{
"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:
```json
{
"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](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](https://partners.viber.com/) |
| `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](https://partners.viber.com/)
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
```bash
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 (43 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](LICENSE) © [Serhii Zghama](https://github.com/serhiizghama)