agent-voice-mcp-minus

agent-voice-mcp enhanced edition · local MCP voice broadcast service that provides task progress voice announcements for AI coding assistants (Trae / Claude Desktop / Cursor, etc.), deeply adapted to Volcengine Doubao speech synthesis large model (seed-tts).

This project is forked from al96169/agent-voice-mcp (author Antonio Liang, MIT license), and has been heavily tested and tuned against the Volcengine v3 API and real-world usage scenarios. The original is the core; this project is the core + production hardening. All enhancements can be disabled via configuration switches, falling back to behavior close to the original.

Enhancements (relative to original 1.2.0)

1. Installation

Prerequisites

• Node.js ≥ 18 (download)

• Windows (cloud synthesis works cross-platform; SAPI fallback and beep cue tones are Windows-only, other platforms degrade gracefully)

• Volcengine account (requires enabling the speech synthesis large model service, see Step 2)

Step 1: Configure the MCP client

Option A · Run directly via npx (recommended, no cloning needed)

Add to your MCP client configuration (Trae: .trae/mcp.json in the project directory; Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json):

{
  "mcpServers": {
    "agent-voice": {
      "command": "npx",
      "args": ["-y", "github:doer1296/agent-voice-mcp-minus"]
    }
  }
}

Option B · Clone the repo and run locally (recommended for users who want to modify code)

git clone https://github.com/doer1296/agent-voice-mcp-minus.git
cd agent-voice-mcp-minus
npm install

Change the MCP config to connect directly via node (faster startup, unaffected by the npm registry):

{
  "mcpServers": {
    "agent-voice": {
      "command": "node",
      "args": ["D:/your/path/agent-voice-mcp-minus/dist/index.js"]
    }
  }
}

After configuration, restart the client / open a new session. When the MCP service starts, it will announce "agent-voice service started" to indicate readiness.

Step 2: Obtain Volcengine credentials

1. Register/log in to Volcengine

2. In the console, search for "Voice Technology" → enable the "Speech Synthesis Large Model" service (free quota available for new users)

3. On the "API Key Management" page, create and obtain your X-Api-Key

4. Note: you must enable the model resource matching the voice you use (seed-tts-1.0 or seed-tts-2.0, see Large Model Settings)

Free alternative: the original includes the Edge TTS engine (Microsoft free online synthesis, no API Key required, hundreds of voices). Set engine to "edge-tts" to use it; see the original README for details.

Step 3: Create the configuration file

Copy config.example.json from this repo to:

Windows: C:\Users\<你的用户名>\.agent-voice\config.json
macOS / Linux: ~/.agent-voice/config.json

Then replace the apiKey field with your X-Api-Key (choose one of two):

• Plaintext directly: "apiKey": "your-key"

• Environment variable reference (recommended): keep "${VOLCANO_API_KEY}", then set the system environment variable VOLCANO_API_KEY=your-key (the config file supports ${ANY_ENV_VAR_NAME} syntax, avoiding plaintext keys on disk)

2. How to call (Agent-side usage)

The MCP service registers the speak tool; the Agent calls it to broadcast:

Recommended: use project rules to let the Agent automatically announce the task lifecycle. Add to Trae's .trae/rules/project_rules.md (or Claude's CLAUDE.md):

在每次任务中，调用 agent-voice MCP 进行语音播报：
1. 任务开始时 — scene="task_start"
2. 每个子任务完成时 — scene="milestone"
3. 任务全部完成时 — scene="task_complete"
4. 遇到错误时 — scene="task_error"
5. 需要用户确认时 — scene="need_interaction"

Call example:

speak(text="开始执行任务：重构登录模块", scene="task_start", emotion="calm")
speak(text="任务完成，测试全部通过", scene="task_complete", emotion="happy")

Other tools: stop (stop current broadcast and clear queue), get_voices (list available voices), get_roles (list configured roles).

3. How to set the large model (model selection)

In config.json, cloud.resourceId determines which speech synthesis large model is used:

⚠️ Voice and model version must match: using _moon_bigtts voices with seed-tts-2.0 (or vice versa) returns HTTP 403 resource not authorized. When switching models, remember to switch voice IDs accordingly, and enable the corresponding model service in the Volcengine console.

Selection advice: 1.0 is stable, has rich voices, and mature documentation; 2.0 supports new capabilities such as voice cloning. All tuning in this project is tested and verified against 1.0.

4. How to change voices

Modify cloud.voice in config.json (plus the individual voice fields in each scene config), and make sure it matches the resourceId version:

seed-tts-1.0 示例：
  zh_female_daimengchuanmei_moon_bigtts   呆萌川妹（甜美女声，本项目默认）
  zh_female_qingxinnvsheng_mars_bigtts    清新女声

seed-tts-2.0 示例：
  zh_female_vv_uranus_bigtts              温柔女声
  zh_male_*.uranus_bigtts                 男声系列

For the full voice list, see the Volcengine voice library documentation.

5. How to adjust volume / rate

Volume volume (default 1.3):

• Mapping: loudness_rate = (volume − 1) × 100, i.e. 1.0 = original loudness, 1.3 = +30% (measured RMS gain ≈ +29%, near-linear)

• Recommended range 0.5 – 2.0; 2.0 = +100% (server-side ceiling)

• Global default lives at the top-level volume; each scene can override it (scenes.*.volume)

Rate rate (default 200):

• Mapping: speech_rate = (rate / 200 − 1) × 100, i.e. 200 = original speed, 220 = +10%, 180 = −10%

• Default scene gradient (recommended based on this project's testing): start 190 → interaction 200 → milestone/error 210 → complete 220

6. Bluetooth leading silence (important)

cloud.leadingSilence (default 1500, i.e. 1.5 seconds):

This parameter is designed for Bluetooth headset users. Establishing the Bluetooth audio link takes about 1–2 seconds; at broadcast start the headset is often not yet connected, causing the first word to be swallowed by connection noise. This parameter inserts the specified number of milliseconds of full silence at the very front of the audio data, so speech only begins once the Bluetooth link is ready.

• Bluetooth headset users: keep 1500 (increase to 2000 if words are still swallowed)

• Wired headset / speaker users: set it to 0 for more compact broadcasts

• The pre-broadcast cue tone is itself audio output that wakes the Bluetooth link early, working in tandem with this parameter

7. Full parameter table

Backup broadcast channel (watcher, optional)

watcher/voice-watcher.mjs is a resident listener that does not depend on the MCP connection: it polls ~/.trae-cn/work/.voice-reader/pending.txt, and whenever it finds tagged content, it broadcasts it using the same cloud engine as the main service (config, voice, and volume always read from the same source; SAPI fallback also applies on cloud failure).

Use case: when MCP tools are unavailable in an Agent session (e.g. model switching, MCP service crash), you can still write a tag to the file to trigger a broadcast, forming a fallback channel:

[VOICE_READER_START:success]
要播报的文本
[VOICE_READER_END]

Types support info / success / error / warning, mapping to the task_start / task_complete / task_error / need_interaction scene parameters respectively.

How to enable: set "watcher": { "enabled": true } in config.json. When the main MCP service starts, it automatically spawns the watcher as a child process and reaps it on exit (TCP single-instance guard on port 47613, so only one instance runs across multiple sessions). You can also run it standalone: node watcher/voice-watcher.mjs.

Portable paths: all paths are relative derivations or os.homedir() concatenations, with no hardcoded absolute paths. Environment variables can override: AGENT_VOICE_CONFIG (config file path), AGENT_VOICE_PENDING_DIR (directory containing pending.txt, default ~/.trae-cn/work/.voice-reader, adaptable to other MCP clients).

Notes

1. Configuration is loaded once at MCP startup. After modifying config.json, restart the client / open a new session for changes to take effect (it does not re-read on every broadcast).

2. Sample rate and channels: testing shows the real bandwidth of this voice is ≤ 12kHz; requesting 32/44.1/48kHz only performs interpolated upsampling with no quality gain (verified via multi-window FFT band analysis); the API only supports mono, and the system automatically mixes to both ears on playback. Keeping 24000 is optimal.

3. Emotion is implemented client-side: the v3 API for seed-tts-1.0 does not support a server-side emotion parameter (testing shows it is silently ignored). This project expresses six emotions via combinations of pitch (pitch ±12) + rate/volume offsets, with emotionIntensity controlling the strength.

4. Do not enable SSML: testing shows SSML <break> pause tags truncate audio on the 1.0 + v3 streaming API (only the first sentence is synthesized). Long-text pauses are already implemented via the client-side solution, so SSML is unnecessary.

5. Quota and billing: Volcengine bills per character, so task announcement text should be kept short (the default 200-character truncation in this project is partly for this reason); when quota is exhausted it automatically degrades to local SAPI speech (the voice will change, which is normal).

6. Windows dependency: cue tones use System.Console::Beep, and speech playback uses PowerShell Media.SoundPlayer—both built into Windows, but if PowerShell is disabled by group policy, the related features degrade.

7. Output directory: synthesized audio is written to the system temp directory, deleted automatically after playback, leaving no residue.

Acknowledgements

• agent-voice-mcp and original author Antonio Liang — this project is an enhancement of their MIT open-source code; core designs such as voice roles and the multi-engine architecture all come from the original

• Volcengine · Doubao Speech Synthesis Large Model

License

MIT (inherits the original project's license, retaining the original author's attribution)