Content
# Aivis Cloud MCP Server
It makes the voice synthesis function available using [Aivis Cloud API](https://hub.aivis-project.com/).
Voice synthesis and playback are designed to be performed in the background, so they do not interfere with development efficiency.
# Demo
https://github.com/user-attachments/assets/c42722bd-8f2f-4543-bdc6-71668db3751d
## Features
- **Immediate Response**:
Generates and plays audio in the background, immediately returning `OK`
- **Streaming Playback**: Plays audio data in real-time while receiving it
- **Sequential Playback with Queue**:
Plays sequentially in the Redis queue, preventing audio overlap even with multiple processes/multiple simultaneous calls
- **Instant Execution with npx**: No installation required, can be used immediately with `npx aivis-mcp`
- **Minimal Environment Variables**: Only the API key is required, others can be set with CLI arguments
## Requirements
- Node.js 18.x or higher
- Aivis Cloud
API key (obtained from [Aivis Hub](https://hub.aivis-project.com/cloud-api/api-keys))
- Audio player (ffplay recommended, also supports mpv, afplay)
- Redis (running locally)
> [!TIP]
> You can check and install dependent tools with `npx aivis-mcp --doctor`
## Setup
### 1. Initial Settings
```bash
npx aivis-mcp --init
```
Saves the API key, etc., to `~/.config/aivis-mcp/config.json`.
Once set, it will be automatically loaded by both CLI and MCP.
### 2. Check Dependent Tools
```bash
npx aivis-mcp --doctor
```
If Redis or FFmpeg is not installed, you can install them interactively.
### 3. MCP Server Registration
#### Claude Code
```bash
claude mcp add aivis -s user -- npx -y aivis-mcp
```
#### Codex
```bash
codex mcp add aivis -- npx -y aivis-mcp
```
<details>
<summary>Claude Desktop / Cursor / Antigravity IDE / Other (JSON Settings)</summary>
**Claude Desktop / Cursor / Antigravity IDE**
Add to the MCP configuration file of each client:
```json
{
"mcpServers": {
"aivis": {
"command": "npx",
"args": ["-y", "aivis-mcp"],
"env": {
"AIVIS_API_KEY": "your_api_key_here"
}
}
}
}
```
To specify models and audio parameters:
```json
{
"mcpServers": {
"aivis": {
"command": "npx",
"args": ["-y", "aivis-mcp", "--model", "your-model-uuid", "--rate", "1.2"],
"env": {
"AIVIS_API_KEY": "your_api_key_here"
}
}
}
}
```
</details>
## CLI Arguments
Options that can be used when starting the MCP server or with CLI commands:
| Argument | Short | Description | Default |
|------|------|------|----------|
| `--api-key` | `-k` | API key | Environment variable `AIVIS_API_KEY` |
| `--model` | `-m` | Model UUID | `a59cb814-...` |
| `--rate` | `-r` | Speaking rate | - |
| `--pitch` | `-p` | Pitch | - |
| `--volume` | | Volume | - |
| `--style-name` | | Style name | - |
| `--style-id` | | Style ID | - |
| `--emotional-intensity` | | Emotional intensity | - |
| `--tempo-dynamics` | | Tempo dynamics | - |
| `--leading-silence` | | Leading silence (seconds) | - |
| `--trailing-silence` | | Trailing silence (seconds) | - |
| `--line-break-silence` | | Line break silence (seconds) | - |
| `--api-url` | | API endpoint | `https://api.aivis-project.com/v1` |
| `--redis-url` | | Redis connection | `redis://127.0.0.1:6379` |
| `--debug` | `-d` | Debug mode | off |
> [!NOTE]
> All CLI arguments can also be set as environment variables (e.g., `--rate` → `AIVIS_SPEAKING_RATE`).
> CLI arguments > Environment variables > Default values are applied in order of priority.
## CLI Commands
You can execute voice synthesis directly from the terminal, not just as an MCP server.
```bash
# Via npx
npx aivis-mcp "hello"
npx aivis-mcp "hello" --model your-model-uuid
npx aivis-mcp "hello" --rate 1.2 --pitch 0.5
# If globally installed
aivis "hello"
aivis "hello" --model your-model-uuid
# Utilities
npx aivis-mcp --doctor # Dependent tool diagnosis/installation
npx aivis-mcp --health # Health check
npx aivis-mcp --reboot # Reboot all processes
npx aivis-mcp --version # Show version
```
The CLI is played back via the same Redis queue as the MCP, so the command returns immediately.
Exclusive control is also performed with playback via MCP, so the voices will not overlap at the same time.
If the worker is not running, it will start automatically.
## For Developers
```bash
git clone https://github.com/MocA-Love/aivis-mcp.git
cd aivis-mcp
npm install
```
<details>
<summary>Redis Installation</summary>
### macOS
```bash
brew install redis
```
### Windows
```powershell
winget install Redis.Redis
```
### Linux (Ubuntu/Debian)
```bash
sudo apt update
sudo apt install redis-server
```
### Linux (Fedora)
```bash
sudo dnf install redis
```
</details>
<details>
<summary>FFmpeg Installation</summary>
### macOS
```bash
brew install ffmpeg
```
### Linux (Ubuntu/Debian)
```bash
sudo apt update
sudo apt install ffmpeg
```
### Linux (Fedora)
```bash
sudo dnf install ffmpeg
```
### Windows
- Download from [FFmpeg official website](https://ffmpeg.org/download.html)
> [!NOTE]
> If ffplay is not installed, playback will be via a temporary file, causing a delay.
</details>
## Example Usage
By registering it as a custom command like [aivis.md](./aivis.md), you can easily have it report in voice.
## Architecture
```
┌─────────────────┐ ┌─────────────────┐
│ Claude Desktop │ │ Terminal │
└────────┬────────┘ │ aivis "hello" │
│ MCP Protocol └────────┬────────┘
┌────────▼────────┐ │
│ MCP Server │ │
│ (index.ts) │ │
└────────┬────────┘ │
│ │
┌────────▼────────┐ ┌───────▼─────────┐
│ MCP Service │ │ CLI │
│ (mcp-service.ts)│ │ (cli.ts) │
└────────┬────────┘ └───────┬─────────┘
│ │
│ ┌───────────┐ │
└───▶│ Redis │◀───┘
│ Queue │ Both enqueue to the queue
└─────┬─────┘
│ dequeue
┌────────▼──────────┐
│ Worker Process │
│ (aivis-speech-svc)│
│ Exclusive control│
│ with play-lock │
└────────┬──────────┘
│
┌───────▼───────┐ ┌──────────┐
│ Aivis Cloud │ │ ffplay/ │
│ API │────▶│ mpv │
└───────────────┘ └──────────┘
Voice generation Streaming playback
```
## Changelog
See [CHANGELOG.md](./CHANGELOG.md).
