aivis-mcp

# Aivis Cloud MCP Server MCP server using Aivis Cloud API. Enables voice synthesis function. Voice synthesis and playback are designed to run in the background so as not to 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 (R:xxxxms)` - **Streaming Playback**: Plays audio data in real-time while receiving it - **Sequential Playback with Queue**: Plays audio sequentially using a Redis queue, preventing audio overlap even with multiple processes/simultaneous calls - **Cross-Platform Compatibility?**: Should work on Windows and macOS (only tested on Mac) ## Requirements - Node.js 18.x or higher - npm 9.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) ## Installation ```bash # Clone the repository git clone https://github.com/MocA-Love/aivis-mcp.git cd aivis-mcp # Install dependencies npm install # Build npm run build # Configure environment variables cp .env.example .env # Edit the .env file and set the API key ``` ## Redis Installation ### 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 ``` ## FFmpeg Installation ### 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 the [FFmpeg official website](https://ffmpeg.org/download.html) > [!NOTE] > If ffplay is not installed, playback will be via a temporary file, causing delays. ## Configuration Configure the following settings in the `.env` file: ```env AIVIS_API_KEY=your_api_key_here # Required: Aivis Cloud API key AIVIS_API_URL=https://api.aivis-project.com/v1 # API endpoint (usually no need to change) REDIS_URL=redis://127.0.0.1:6379 # Redis connection destination (usually no need to change) ``` > [!TIP] > Changes to the `.env` file are automatically detected, and the new settings will be reflected from the next request. Restarting Claude > Desktop is not required. ## Registering with Claude Code ```bash # Register the MCP server claude mcp add aivis \ -s user \ -- node /full/path/to/aivis-mcp/dist/index.js # To remove the registration claude mcp remove aivis ``` ## Registering with Codex ```bash codex mcp add aivis -- node /Users/magu/github/aivis-mcp/dist/index.js ``` ## Registering with Antigravity In the Antigravity IDE, configure `~/.gemini/antigravity/mcp_config.json` as follows: ```json { "mcpServers": { "aivis": { "command": "node", "args": [ "/full/path/to/aivis-mcp/dist/index.js" ], "env": { "AIVIS_API_KEY": "your_api_key_here", "AIVIS_API_URL": "https://api.aivis-project.com/v1", "AIVIS_MODEL_UUID": "your_model_uuid_here" } } } } ``` ## Usage ``` "Say 'Hello' with aivis mcp" ``` ### Parameter Specification Example ```json { "text": "Hello", "model_uuid": "your-model-uuid" } ``` ## Custom Commands You can easily have it report in voice by registering it as a custom command in Claude Code, such as aivis.md. ## Customizing Voice Parameters Voice synthesis parameters are set via environment variables. You can customize the following values in the `.env` file: | Environment Variable | Description | Range/Default Value | | -------------------------------- | -------------------------- | ------------------------- | | AIVIS_MODEL_UUID | Model UUID | - | | AIVIS_STYLE_ID | Style ID | 0-31 | | AIVIS_STYLE_NAME | Style Name | - | | AIVIS_SPEAKING_RATE | Speaking Rate | 0.5-2.0 (Default: 1.0) | | AIVIS_EMOTIONAL_INTENSITY | Emotional Intensity | 0.0-2.0 (Default: 1.0) | | AIVIS_TEMPO_DYNAMICS | Tempo Dynamics | 0.0-2.0 (Default: 1.0) | | AIVIS_PITCH | Pitch | -1.0-1.0 (Default: 0.0) | | AIVIS_VOLUME | Volume | 0.0-2.0 (Default: 1.0) | | AIVIS_LEADING_SILENCE_SECONDS | Silence at Start (seconds) | 0.0- (Default: 0) | | AIVIS_TRAILING_SILENCE_SECONDS | Silence at End (seconds) | 0.0- (Default: 0) | | AIVIS_LINE_BREAK_SILENCE_SECONDS | Silence at Line Break (sec)| 0.0- (Default: 0) | ## Architecture ``` ┌─────────────────┐ │ Claude Desktop │ └────────┬────────┘ │ MCP Protocol ┌────────▼────────┐ │ MCP Server │ │ (index.ts) │ └────────┬────────┘ │ ┌────────▼────────┐ │ MCP Service │ ← Immediate Response │ (mcp-service.ts)│ Returns "OK" immediately └────────┬────────┘ │ ┌────────▼────────────┐ │ Worker Process │ ← Processes Queue Sequentially │ (aivis-speech-svc) │ Voice Synthesis and Playback └──────┬──────────────┘ │ ┌──────▼────────┐ │ Redis │ │ Queue │ └──────┬────────┘ │ ┌──────▼────────┐ ┌──────────┐ │ Aivis Cloud │ │ ffplay/ │ │ API │────▶│ mpv │ └───────────────┘ └──────────┘ Voice Generation Streaming Playback ```