Skip to main content
Glama

voicevox-assistant-mcp

English | 日本語

A voice assistant for Claude Code that reads out a short spoken summary of each reply with VOICEVOX. Like JARVIS or an anime android, it tells you only the conclusion in a calm voice, and drops an occasional acknowledgement or progress report while it works.

Disclaimer: This is an independent, personal project. It is not affiliated with, endorsed by, or officially connected to the VOICEVOX developers, the voice characters' rights holders, or Anthropic.

Features

Status

Feature

✅

Reads a 1–3 sentence summary of every reply (no paths, code, URLs or boilerplate)

✅

Acknowledges each request ("承知しました" — "Understood")

✅

Random fillers and progress reports while working, matched to the tool ("Running the tests")

✅

Tells you when it is waiting for you: permission prompts, questions, plan approval

✅

Four voice presets (JARVIS-like butler, android, operator, robot)

✅

Quiet mode (stops speech and fillers)

✅

No overlapping voices across sessions and windows (one player per machine)

✅

Plays the first sentence while synthesizing the next

Speech is in Japanese by default; Claude is told to speak in the user's language.

Related MCP server: VoiceVox MCP Server

How it works

Claude Code ──(stdio)── MCP server ─┐
Claude Code ──(stdio)── MCP server ─┼─ HTTP 127.0.0.1:38121 ─→ hub (first server started) ─→ VOICEVOX
hooks (fillers) ────────────────────┘                             │                         127.0.0.1:50021
                                                                    └─→ speakers (winsound)
  • Claude writes the summary itself. The MCP server's instructions tell Claude to call speak at the end of every reply with an ear-friendly summary in a JARVIS-like tone.

  • Hub: the first MCP server to start listens on 127.0.0.1; other servers and the hooks send to it. When it exits, the next server that needs to speak takes over.

  • Fillers: the hook only picks a phrase and posts it to the hub, then exits immediately, so Claude is never slowed down. The hub skips a filler while speaking, in quiet mode, or right after speaking. speak interrupts fillers.

  • Waiting alerts: when Claude asks a question (AskUserQuestion), asks to approve a plan (ExitPlanMode) or shows a permission prompt (Notification), it always says so — queued after current speech, never throttled, silent only in quiet mode.

Requirements

  • Windows (playback uses winsound)

  • Python: 3.11 or higher (uv provides it)

  • uv

  • VOICEVOX: the engine running at http://127.0.0.1:50021 (start the app)

  • Claude Code (CLI or the VS Code extension)

Installation (user-wide, available in every project)

1. Install the commands

uv tool install git+https://github.com/hirotoitpost/voicevox-assistant-mcp

This puts voicevox-assistant-mcp (MCP server) and voicevox-assistant-hook (fillers) in ~/.local/bin.

2. Register the MCP server for your user

claude mcp add --scope user voice-assistant -- voicevox-assistant-mcp

If you only use the VS Code extension and have no claude command, use the bundled binary: %USERPROFILE%\.vscode\extensions\anthropic.claude-code-<version>-win32-x64\resources\native-binary\claude.exe

3. Add the hooks and permission

Add to ~/.claude/settings.json (merge into existing permissions / hooks if present):

{
  "permissions": {
    "allow": ["mcp__voice-assistant"]
  },
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "voicevox-assistant-hook", "timeout": 3 }] }
    ],
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "voicevox-assistant-hook", "timeout": 3 }]
      }
    ],
    "Notification": [
      { "hooks": [{ "type": "command", "command": "voicevox-assistant-hook", "timeout": 3 }] }
    ]
  }
}

Without the permission entry, Claude Code asks before every spoken summary.

4. Restart

Restart Claude Code (in VS Code: "Developer: Reload Window").

Update / uninstall

On Windows, files in use cannot be replaced: close every Claude Code session and VS Code window first (the MCP server is running), then update from a separate terminal.

uv tool upgrade voicevox-assistant-mcp    # update, then restart
uv tool uninstall voicevox-assistant-mcp  # also run: claude mcp remove voice-assistant, and remove the hooks

Usage

Just talk to Claude.

  • "静かに" / "be quiet" → stops speech and fillers. "読み上げ再開" / "resume speaking" turns them back on

  • "アンドロイドの声にして" / "use the android voice" → changes the voice

Voice presets

Preset

Voice

jarvis (default)

VOICEVOX:青山龍星 (しっとり) — calm butler

android

VOICEVOX:ナースロボ_タイプT (ノーマル)

announce

VOICEVOX:No.7 (アナウンス) — cool operator

voidoll

VOICEVOX:Voidoll (ノーマル)

Follow each character's terms of use: credit "VOICEVOX:(character name)" when publishing recorded audio.

MCP tools

Tool

Description

speak(text, preset?, interrupt?)

Speak a summary (returns immediately)

stop_speaking()

Stop speaking and clear the queue

set_quiet(on)

Toggle quiet mode

set_voice(preset)

Change the default voice

voice_presets()

Presets, current state and engine status

Configuration (environment variables)

Variable

Default

Meaning

VOICEVOX_URL

http://127.0.0.1:50021

VOICEVOX engine URL

VOICE_ASSISTANT_PRESET

jarvis

Default voice

VOICE_ASSISTANT_PORT

38121

Hub port (127.0.0.1 only)

VOICE_ASSISTANT_FILLER

on

off disables fillers

VOICE_ASSISTANT_FILLER_RATE

0.5

Chance of a filler on each tool call

VOICE_ASSISTANT_FILLER_GAP

25

Seconds of silence required before a filler

VOICE_ASSISTANT_ACK_RATE

0.8

Chance of acknowledging a request

VOICE_ASSISTANT_PERMISSION_ALERT

on

Say so when a permission prompt appears

VOICE_ASSISTANT_IDLE_ALERT

off

Say so when Claude has been waiting for input (the summary already says it's done)

Pass them to the MCP server with claude mcp add ... -e VOICE_ASSISTANT_PRESET=android -- voicevox-assistant-mcp, and to the hooks with env in settings.json. If you change the port, set the same value in both.

Troubleshooting

Symptom

Check

No speech at all

Is VOICEVOX running? See engine.ready in voice_presets

Summaries but no fillers

Hooks in settings.json; is voicevox-assistant-hook on PATH?

Hub fails to start

Windows reserves some ports at 49152+ for Hyper-V. Check netsh interface ipv4 show excludedportrange protocol=tcp and set VOICE_ASSISTANT_PORT to a free port

Asked for permission every time

Add mcp__voice-assistant to permissions.allow

Limitations

  • It cannot interrupt while Claude is thinking; fillers happen between tool calls

  • Summary quality depends on Claude

  • Playback is Windows-only (other OSes stop after synthesizing the wav)

Development

git clone https://github.com/hirotoitpost/voicevox-assistant-mcp.git
cd voicevox-assistant-mcp
uv sync
uv run ruff check .
uv run pytest

To try local code: claude mcp add --scope user voice-assistant -- uv --directory <path> run voicevox-assistant-mcp. See CONTRIBUTING.md and SECURITY.md.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers