Skip to main content
Glama

vv-mcp

VOICEVOX MCP Server - Claude DesktopとClaude Codeで音声合成を利用するためのMCPサーバー

必要要件

  • Node.js 18以上

  • VOICEVOXがインストールされ、起動していること

  • サポートOS:

    • macOS: afplayを使用(追加インストール不要)

    • Linux: pw-play(PipeWire)または paplay(PulseAudio)が必要

      • PipeWire環境では pw-play を優先的に使用し、なければ paplay にフォールバック

      • PipeWire:

        • Arch Linux: pacman -S pipewire

        • Ubuntu/Debian: apt install pipewire-bin

        • Fedora: dnf install pipewire-utils

      • PulseAudio:

        • Arch Linux: pacman -S pulseaudio

        • Ubuntu/Debian: apt install pulseaudio-utils

        • Fedora: dnf install pulseaudio-utils

    • Windows: PowerShellを使用(追加インストール不要)

Related MCP server: VOICEPEAK MCP Server

インストール

npmからインストール(推奨)

npm install -g @arrow2nd/vv-mcp

ソースからビルド

git clone https://github.com/arrow2nd/vv-mcp.git
cd vv-mcp
npm install
npm run build

Claude Desktopでの設定

設定ファイルを編集:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

npmでインストールした場合

{
  "mcpServers": {
    "vv-mcp": {
      "command": "npx",
      "args": ["-y", "@arrow2nd/vv-mcp"],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "DEFAULT_VOICE_ID": "47",
        "DEFAULT_SPEED": "1.0"
      }
    }
  }
}

ソースからビルドした場合

{
  "mcpServers": {
    "vv-mcp": {
      "command": "node",
      "args": ["/path/to/vv-mcp/dist/index.js"],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "DEFAULT_VOICE_ID": "47",
        "DEFAULT_SPEED": "1.0"
      }
    }
  }
}

Claude Codeでの設定

~/.claude.jsonmcpServersセクションに以下を追加:

npx/bunxを使用する場合(推奨)

{
  "mcpServers": {
    "vv-mcp": {
      "command": "npx",
      "args": ["-y", "@arrow2nd/vv-mcp"],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "DEFAULT_VOICE_ID": "47",
        "DEFAULT_SPEED": "1.0"
      }
    }
  }
}

bunxを使用する場合は"command": "bunx"に変更してください。

ソースからビルドした場合

{
  "mcpServers": {
    "vv-mcp": {
      "command": "node",
      "args": ["/path/to/vv-mcp/dist/index.js"],
      "env": {
        "VOICEVOX_URL": "http://localhost:50021",
        "DEFAULT_VOICE_ID": "47",
        "DEFAULT_SPEED": "1.0"
      }
    }
  }
}

使用方法

Claude Desktop/Codeを再起動後、以下のMCPツールが利用可能になります:

利用可能なツール

  • say - テキストを音声合成して再生(非同期実行)

  • list_voices - 利用可能な音声一覧を取得

  • get_queue_status - 再生キューの状態を確認

  • clear_queue - 再生キューをクリア

  • get_voices_in_use - 現在使用中の音声IDのリストを取得(全プロセス共通)

  • get_random_unused_voice - 使用されていない音声をランダムに1つ取得

  • get_session_voice - このセッションで使用する音声を取得(セッション毎に固定)

使用例

「こんにちは」と言って
ナースロボの楽々な声で「完了しました」と言って
利用可能な音声を教えて

セッション音声機能

各Claudeセッションに固定の音声を自動割り当てする機能があります:

使用方法

# セッション音声を使用して読み上げ
"こんにちは"とセッション音声で言って

sayツールのパラメータ

  • useSessionVoice: true - セッション音声を使用(voiceIdは無視される)

  • useSessionVoice: false(デフォルト) - 指定した音声IDまたはデフォルト音声を使用

仕組み

  • セッション開始時に自動的に音声を選択

  • 他のセッションと重複しない音声を優先的に選択

  • 全音声が使用中の場合は使用頻度の低い音声を選択

  • セッション終了時に自動的に音声を解放

複数インスタンス対応

複数のClaude Desktop/Codeが同時に動作している場合、自動的に異なる音声を使用して音声の重複を避けます。

  • 各プロセスで使用中の音声情報を共有

  • get_random_unused_voiceツールで未使用の音声を自動選択

  • 一時ディレクトリに状態ファイルを作成して情報を共有

環境変数

変数名

デフォルト値

説明

VOICEVOX_URL

http://localhost:50021

VOICEVOX APIのURL

DEFAULT_VOICE_ID

47

デフォルトの音声ID (ナースロボ_タイプT)

DEFAULT_SPEED

1.0

デフォルトの話速

VV_MCP_STATE_DIR

システム一時ディレクトリ

共有状態ファイルの保存ディレクトリ

ライセンス

MIT

Available Tools

7 tools
clear_queueB

再生キューをクリア

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, yet the description fails to disclose critical behavioral traits of this destructive operation, such as whether clearing affects the currently playing item, if the action is reversible, or what permissions are required. It states the action without explaining state impact or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of a single three-word Japanese phrase with zero redundant text or wasted structure. However, given the lack of annotations and the destructive nature of the operation, the extreme brevity may be insufficient rather than optimally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

As a state-mutating tool with no annotations, no output schema, and undocumented behavioral implications, the description leaves significant gaps regarding what exactly gets cleared and the consequences of invocation. It meets the bare minimum of stating the action but lacks necessary operational context for safe usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema contains zero parameters, establishing a baseline score of 4 per the evaluation rules. The description correctly omits parameter details since none exist to document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states '再生キューをクリア' (clear the playback queue), providing a specific verb and resource that aligns with the tool name. While it clarifies that 'queue' refers specifically to the playback queue, it does not explicitly differentiate this tool from sibling operations like `say` (which likely adds items) or `get_queue_status`.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no guidance on when to invoke this tool versus alternatives, nor does it mention prerequisites or side effects. There is no indication of whether this should be used before `say` operations, during active playback, or only when the queue is in a specific state.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_queue_statusB

再生キューの状態を取得

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It fails to mention whether this is a read-only operation, what the 'status' includes, return format, or any side effects. The description only states the basic action without behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence with no wasted words. However, given the lack of annotations and output schema, it may be overly minimal rather than appropriately sized for complete understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool, the description minimally suffices to identify the tool's domain (playback queue). However, without an output schema or annotations, it lacks necessary details about what status information is returned, making it only adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, establishing a baseline score of 4. The description does not need to compensate for missing schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves (取得) the playback queue (再生キュー) status (状態), providing a specific verb-resource pair. However, it does not explicitly differentiate from sibling 'clear_queue' in the description text, though the tool name implies the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'clear_queue' or 'say', nor does it mention prerequisites or conditions for invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_random_unused_voiceA

使用されていない音声をランダムに1つ取得

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the random selection behavior and the 'unused' filtering criteria, which adds necessary context. However, with no annotations provided, it fails to clarify critical behavioral traits: whether retrieving a voice marks it as 'used' (state mutation), what happens when no unused voices remain, or the return value structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient 12-character Japanese sentence that conveys the complete operation without redundancy or wasted words. Information density is maximized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description covers the core retrieval logic, it lacks necessary completeness given the absence of annotations and output schema. It omits the return value format (voice ID? object? name?) and error conditions (empty pool handling), which are essential for a zero-parameter tool with no schema documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema contains zero parameters, establishing a baseline score of 4. The description appropriately requires no additional parameter clarification given the tool's simple, fixed operation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool retrieves 'one random unused voice' (使用されていない音声をランダムに1つ取得), providing specific verb (取得/retrieve), resource (音声/voice), and scope constraints (unused, random, single item). It clearly distinguishes from sibling get_voices_in_use by filtering for unused voices rather than active ones.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like list_voices (which presumably returns all voices) or get_session_voice. It does not indicate whether this is for initial voice selection, rotation scenarios, or queue management.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_session_voiceA

このセッションで使用する音声を取得(セッション毎に固定)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It successfully discloses idempotency/consistency via 'fixed per session,' but fails to describe the return format, potential side effects, or what happens if no voice is assigned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single efficient sentence with action front-loaded ('音声を取得') and critical behavioral context deferred to a parenthetical. Zero redundancy—every character earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the core purpose is clear, the absence of an output schema means the description should ideally characterize the return value (voice ID, name, object structure). As a simple getter, it is minimally viable but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool accepts zero parameters (empty schema), establishing a baseline of 4. The description requires no parameter clarification, though it implicitly confirms no filtering or input is needed to retrieve the session voice.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves (取得) the voice (音声) assigned to the current session (このセッション), with the parenthetical 'fixed per session' (セッション毎に固定) effectively distinguishing it from sibling tools like get_random_unused_voice and list_voices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'fixed per session' constraint implies this returns a persistent/deterministic value versus alternatives, but lacks explicit guidance on when to prefer this over get_random_unused_voice or list_voices, and omits any prerequisites or error conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_voices_in_useA

現在使用中の音声IDのリストを取得(全プロセス共通)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It successfully discloses the global scope ('全プロセス共通'), which is critical behavioral context distinguishing it from session-specific tools. However, it omits safety characteristics (read-only nature, idempotency), error conditions, or performance implications that would be essential for a state-querying tool without annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient Japanese sentence with zero wasted words. It front-loads the action and resource, placing the scope qualifier parenthetically. Every element earns its place: the verb (取得), the resource (音声IDリスト), the state filter (現在使用中), and the scope disambiguator (全プロセス共通).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (zero parameters, simple getter function) and absence of an output schema, the description adequately explains the return value conceptually (a list of voice IDs). It is complete enough for an agent to select and invoke correctly, though explicit mention of error states or empty result handling would elevate it to a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema contains zero parameters. Per the calibration rules for 0-param tools, the baseline score is 4. The description does not need to compensate for missing parameter documentation, and none are present to describe.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb '取得' (get/retrieve) and clearly identifies the resource as '現在使用中の音声IDのリスト' (list of currently in-use voice IDs). The parenthetical '(全プロセス共通)' (common across all processes) effectively distinguishes this from the sibling tool get_session_voice by explicitly stating its global scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context through the 'all processes' scope qualifier, suggesting when to use this versus session-specific alternatives. However, it lacks explicit guidance on when-not-to-use or direct comparison to siblings like get_session_voice or list_voices.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_voicesB

利用可能な音声の一覧を取得

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It fails to indicate whether the results are cached, the expected return format (e.g., list of IDs vs. objects), or if there are rate limits. The statement is purely functional.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence with no redundant words. Given the simplicity of this parameter-less list operation, the length is appropriate and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description covers the basic purpose, it lacks information about the return structure since no output schema exists. For a catalog-listing tool, mentioning that it returns all configured voice options or the data format would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool accepts zero parameters. Per the evaluation rules, the baseline score for zero-parameter tools is 4. The schema requires no additional semantic clarification from the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description '利用可能な音声の一覧を取得' (Get a list of available voices) provides a clear verb and resource. However, it does not explicitly differentiate from siblings like 'get_voices_in_use' or 'get_random_unused_voice', which also retrieve voice information.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no guidance on when to use this tool versus alternatives such as 'get_voices_in_use' (for active voices) or 'get_random_unused_voice' (for random selection). There are no prerequisites or exclusion criteria stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

sayA

VOICEVOXで音声合成して再生(非同期実行)

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes読み上げるテキスト
voiceIdNo音声ID(デフォルト: 47)
speedNo話速(デフォルト: 1)
useSessionVoiceNoセッション音声を使用するか(デフォルト: false)

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and successfully discloses the asynchronous execution model and audio playback side effect. However, it omits queue behavior, error handling, and whether the operation is destructive or idempotent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single-sentence description is tightly focused, front-loaded with the core action (VOICEVOX synthesis), and contains no redundant information. Every element (engine, action, execution mode) earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter tool with simple types, the description covers the primary function and async nature adequately. However, given the absence of an output schema, it should ideally describe return values (e.g., success confirmation, job ID) or queue interaction effects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the schema adequately documents all parameters. The description does not add parameter-specific semantics beyond what's in the schema, meeting the baseline for high-coverage schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool performs speech synthesis (音声合成) and playback (再生) using the specific VOICEVOX engine, distinguishing it from sibling tools that only query voice metadata or manage queues.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While '非同期実行' (asynchronous execution) implies non-blocking usage, the description lacks explicit guidance on when to use this versus alternatives like get_session_voice or how it interacts with the queue system suggested by sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 7 tool updatesv0.7.0
    • First observedclear_queue
    • First observedget_queue_status
    • First observedget_random_unused_voice
    • First observedget_session_voice
    • First observedget_voices_in_use
    • First observedlist_voices
    • First observedsay

TDQS

A3.7/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose with no ambiguity. For example, 'clear_queue' manages queue state, 'get_queue_status' retrieves status, 'get_random_unused_voice' and 'get_session_voice' handle different voice selection methods, 'get_voices_in_use' lists active voices, 'list_voices' shows all available voices, and 'say' performs synthesis and playback. The descriptions make it easy to differentiate between queue management, voice selection, and playback operations.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case. The verbs are clear and appropriate: 'clear', 'get', 'list', and 'say' are used consistently across tools. There are no deviations in naming conventions, making the set predictable and easy to understand at a glance.

Tool Count5/5

With 7 tools, the server is well-scoped for voice synthesis and playback management. Each tool serves a specific function in the workflow, from listing voices and managing queues to synthesizing speech. The count is neither too sparse nor bloated, fitting the domain of a VOICEVOX interface effectively.

Completeness4/5

The tool set covers core operations for voice synthesis, including voice listing, selection, queue management, and playback. Minor gaps exist, such as the lack of tools for modifying queue order or stopping playback, but agents can work around these using the provided tools (e.g., clearing the queue). Overall, it supports essential workflows without dead ends.

Maintenance

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/arrow2nd/vv-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server