Labsco
shinshin86 logo

AivisSpeech

โ˜… 8

from shinshin86

A server for text-to-speech generation using the AivisSpeech engine.

๐Ÿ”ฅ๐Ÿ”ฅ๐Ÿ”ฅโœ“ VerifiedFreeAdvanced setup
#automation#voice#documents#git#monitoring#translation

MCP Simple AivisSpeech

Project Logo

English | ๆ—ฅๆœฌ่ชž

๐Ÿ™ Special Thanks
This project is based on mcp-simple-voicevox by @t09tanaka.
We deeply appreciate their excellent work in creating the original MCP server for VOICEVOX, which served as the foundation for this AivisSpeech adaptation.

A Model Context Protocol (MCP) server for seamless integration with AivisSpeech text-to-speech engine. This project enables AI assistants and applications to convert text to natural-sounding Japanese speech with customizable voice parameters.

โœจ Features

  • Text-to-Speech Conversion - High-quality Japanese speech synthesis using AivisSpeech
  • Multiple Voice Characters - Support for various speakers and voice styles (default: Anneli ใƒŽใƒผใƒžใƒซ)
  • Configurable Parameters - Adjust speed, pitch, volume, and intonation
  • Cross-Platform Audio - Automatic audio playback on macOS, Windows, and Linux
  • Task Notifications - Voice notifications for process completion
  • Easy Integration - Simple MCP protocol for AI assistant integration
  • Engine Status Monitoring - Real-time status checking of AivisSpeech engine
  • Smart Error Handling - Helpful error messages with speaker suggestions

Task Completion Behavior

  • When all tasks are completed, always use the aivisspeech mcp tool to announce "Tasks completed" via voice
  • When user input or decision is needed, use the aivisspeech mcp tool to announce "Awaiting your decision" via voice

Notification Timings

  • When asking the user a question
  • When all tasks are completed
  • When errors or issues occur

3. Verify the tools are recognized

```bash
claude mcp list

# Or launch Claude Code and use
/mcp

If aivisspeech is displayed, the setup was successful.

๐Ÿ’ก Tip: Claude Code doesn't auto-execute commands for safety. If you forget to start the server, the tools won't appear. During development, keep the above npx command running in a terminal, or use process managers like pm2 or systemd --user for persistent operation.

Using Claude Desktop

For manual configuration with Claude Desktop, you can simply add the following configuration:

Using npx ensures you always get the latest version automatically. No manual updates needed.

{
  "mcpServers": {
    "aivisspeech": {
      "command": "npx",
      "args": ["@shinshin86/mcp-simple-aivisspeech@latest"],
      "env": {
        "AIVISSPEECH_URL": "http://127.0.0.1:10101"
      }
    }
  }
}

๐Ÿ› ๏ธ Available Tools

๐ŸŽค speak

Convert text to speech and play audio with customizable voice parameters.

This tool accepts several configuration parameters, including the following options:

  • text (required): Text to convert to speech
  • speaker (optional): Speaker/voice ID (default: 888753760 - Anneli ใƒŽใƒผใƒžใƒซ)
  • speedScale (optional): Speech speed multiplier (0.5-2.0, default: 1.0)
  • pitchScale (optional): Pitch adjustment (-0.15-0.15, default: 0.0)
  • volumeScale (optional): Volume level (0.0-2.0, default: 1.0)
  • playAudio (optional): Whether to play the generated audio (default: true)

Example usage:

{
  "text": "ใ“ใ‚“ใซใกใฏใ€ไธ–็•Œ๏ผ",
  "speaker": 888753760,
  "speedScale": 1.2,
  "pitchScale": 0.05,
  "volumeScale": 1.5
}

๐Ÿ‘ฅ get_speakers

Retrieve a list of all available voice characters and their styles.

This function returns: List of speakers with their IDs, names, and available voice styles.

๐Ÿ”” notify_completion

Play a voice notification when tasks are completed.

This tool accepts several configuration parameters, including the following options:

  • message (optional): Completion message to announce (default: "ๅ‡ฆ็†ใŒๅฎŒไบ†ใ—ใพใ—ใŸ")
  • speaker (optional): Speaker ID for the notification voice (default: 888753760 - Anneli ใƒŽใƒผใƒžใƒซ)

Example usage:

{
  "message": "ใƒ‡ใƒผใ‚ฟๅ‡ฆ็†ใŒๅฎŒไบ†ใ—ใพใ—ใŸ",
  "speaker": 888753760
}

๐Ÿ“Š check_engine_status

Check the current status and version of the AivisSpeech engine.

This function returns: Engine status, version information, and connectivity details.

๐Ÿ–ฅ๏ธ Platform Support

Audio Playback Systems

PlatformAudio CommandRequirements
macOSafplayBuilt-in (no additional setup)
WindowsPowerShell Media.SoundPlayerWindows PowerShell
LinuxaplayALSA utils (sudo apt install alsa-utils)

Tested Environments

  • macOS 12+ (Intel & Apple Silicon)
  • Windows 10/11
  • Ubuntu 20.04+
  • Node.js 18.x, 20.x, 21.x

๐Ÿงช Development

Available Scripts

# Development & Building
npm run dev          # Run with hot reload (tsx)
npm run build        # Compile TypeScript to dist/
npm start           # Run compiled server

# Code Quality
npm run lint        # Run ESLint
npm run test        # Run Vitest tests (single run)
npm run test:watch  # Run tests in watch mode
npm run test:ui     # Run tests with UI
npm run test:coverage # Run tests with coverage

# Utilities
npm run clean       # Clean dist/ directory

Local vs NPX Usage

When using MCP clients in production, use npx @shinshin86/mcp-simple-aivisspeech@latest in your MCP configuration. No local setup is required, and you always get the latest version.

For development, clone the repository and use npm run dev for hot reload, or npm run build && npm start for testing production builds.

Project Architecture

mcp-simple-aivisspeech/
โ”œโ”€โ”€ src/
โ”‚   โ”œโ”€โ”€ index.ts                  # MCP server & tool handlers
โ”‚   โ””โ”€โ”€ aivisspeech-client.ts     # AivisSpeech API client
โ”œโ”€โ”€ tests/
โ”‚   โ””โ”€โ”€ aivisspeech-client.test.ts # Unit tests
โ”œโ”€โ”€ dist/                         # Compiled output
โ”œโ”€โ”€ docs/                         # Documentation
โ””โ”€โ”€ config files                  # TS, ESLint, Vitest configs

API Client Architecture

The AivisSpeechClient class offers comprehensive functionality, providing several key capabilities:

  • HTTP Client - Axios-based API communication
  • Error Handling - Comprehensive error catching and reporting
  • Type Safety - Full TypeScript interfaces for all API responses
  • Connection Management - Health checks and status monitoring

Adding New Features

  1. New Tool: Add handler in src/index.ts CallToolRequestSchema
  2. API Methods: Extend AivisSpeechClient class
  3. Types: Update interfaces in aivisspeech-client.ts
  4. Tests: Add corresponding test cases

๐Ÿ“„ License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

๐Ÿค Contributing

We welcome contributions from the community. Contributors can get started by completing these essential steps:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Follow existing TypeScript/ESLint configurations
  • Add tests for new functionality
  • Update documentation for API changes
  • Ensure cross-platform compatibility

๐Ÿ™ Acknowledgments

๐Ÿ“ž Support

Made with โค๏ธ for the Japanese TTS community