yak-mcp

Translations: English | 日本語

Demo

This demo includes audio. Please unmute your device and play it.

https://github.com/user-attachments/assets/e9f086b2-13bf-4bf3-9ebc-5ec3d65538ad

Voice: VOICEVOX: ずんだもん

You can freely customize the avatar image. By preparing an animated GIF or APNG, you can create avatars like this:

https://github.com/user-attachments/assets/1143fea3-f8cb-4317-8869-c5e23d893e63

Voice: VOICEVOX: ずんだもん

Related MCP server: mcp-tts

Installation

Download the installer for your platform from the Releases page.

Linux users: I do not have a Linux desktop environment, so I have not been able to verify that yak-mcp works correctly on Linux. I was able to build the Linux version successfully, but I cannot guarantee that it works as expected. Thank you for your understanding.

macOS users: I was unable to build the macOS version in my environment. Please follow the instructions for developers below and try building it yourself. Thank you for your understanding.

Setup

When you launch the application for the first time, the settings window will be displayed. Adjust the settings as needed, then click the Save button to start the MCP server.

From the next launch onward, the MCP server will start automatically. If you want to change the settings, you can open the settings window at any time from the system tray icon.

MCP Server

• Host: Specifies the address on which the MCP server listens.

  • 0.0.0.0 is recommended when accessing it from a devcontainer.

• Port: Specifies the port number on which the MCP server listens.

• REST API: When enabled, yak-mcp also exposes REST API endpoints in addition to the MCP server. This allows agent skills and other applications to use yak-mcp's functionality.

TTS (Text-to-Speech)

You can choose between the built-in Web Speech API and VOICEVOX.

To use VOICEVOX, the VOICEVOX Engine must be running.

Web Speech API

• Language: Select the language to use.

• Volume: Specifies the voice volume.

• Pitch: Specifies the voice pitch.

• Rate: Specifies the speech rate.

VOICEVOX

• Base URL: Specifies the REST API endpoint provided by VOICEVOX Engine. For a standard setup, use http://localhost:50021.

• Speaker ID: Specifies the speaker ID. In a standard setup, access http://localhost:50021/speakers to view the list of speakers and their IDs.

• Volume: Specifies the voice volume.

• Pitch: Specifies the voice pitch.

• Rate: Specifies the speech rate.

Avatar

Configure the behavior of the avatar displayed as a desktop mascot.

• Mirror: Enable this option to flip the avatar image horizontally.

• Animation: Select the animation to apply to the avatar image.

  • None: No animation.

  • Sway: Gently sways from side to side.

  • Weight shift: Slowly shifts its weight from side to side.

  • Breathing: Gently stretches and contracts as if breathing.

  • Float: Slowly moves up and down as if floating.

• Opacity: Specifies the opacity of the avatar image.

• Ignore mouse events: When enabled, mouse events pass through the avatar. Disable this option when moving or resizing the avatar window.

• Emotional states: yak-mcp switches the avatar image based on the emotional state specified by the AI. You can add as many emotional states as you like.

  • Key: Specifies a unique key identifying the emotional state. Keys must not be duplicated.

  • Description: Enter a description that helps the AI select this emotional state.

  • Image file: Specifies the file path to the avatar image. Supported formats are PNG, GIF, JPEG, WebP, and SVG. An absolute path is required.

AI Agent Configuration

yak-mcp can be used with any MCP-compatible AI agent. The only tool provided by yak-mcp is the say tool.

See the sections below for configuration examples for popular AI agents. If you are using Docker Desktop and want to access yak-mcp from a devcontainer, use host.docker.internal instead of localhost.

Codex

Add the following configuration to ~/.codex/config.toml:

[mcp_servers.yak]
url = "http://localhost:39442/mcp"

To always approve the say tool, also add the following configuration to ~/.codex/config.toml:

[mcp_servers.yak.tools.say]
approval_mode = "approve"

Claude Code

Add the following configuration to ~/.claude.json:

{
  "mcpServers": {
    "yak": {
      "type": "http",
      "url": "http://localhost:39442/mcp"
    }
  }
}

To always allow the say tool, add the following configuration to ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__yak__say"
    ]
  }
}

(Optional) Using host.docker.internal from WSL

By adding host.docker.internal to /etc/hosts in WSL, you can connect to the Windows host from WSL using host.docker.internal, just as you would from a Docker container.

To automate this, follow these steps.

1. Create a shell script at any path

In this example, the script is /usr/local/update-hosts.sh.

#!/bin/bash
set -eu

WINDOWS_HOSTNAME="host.docker.internal"

ip_addr=$(ip route | awk '/default/ {print $3}')

sed -i "/[[:space:]]${WINDOWS_HOSTNAME}$/d" /etc/hosts
echo "${ip_addr} ${WINDOWS_HOSTNAME}" >> /etc/hosts

2. Configure WSL to run the script when WSL starts

Add the following to /etc/wsl.conf:

[boot]
systemd=true
command=/usr/local/update-hosts.sh

Testing

Once setup is complete, start your AI agent and send the following message:

use yak.say to say "こんにちは"

If yak-mcp speaks, the setup is complete.

Alternatively, if the REST API is enabled, you can test it with:

curl -X POST http://host.docker.internal:39442/say -d '{"text": "こんにちは", "state":"neutral"}'

Enjoy your chatty and noisy AI agent!

For Developers

Recommended IDE

• VSCode

Development

Install dependencies

pnpm install

Start the development server

pnpm dev

Build for production

# For Windows
$ pnpm build:win

# For macOS
$ pnpm build:mac

# For Linux
$ pnpm build:linux