JinDaGe - windows_tts_mcp MCP Details

article

README

🚀 Windows TTS MCP 服务器

Windows TTS MCP 服务器是一款基于 Windows PowerShell 的文本转语音（TTS）服务器，专为 Claude Desktop 设计，可将文本高效、稳定地转换为语音。

🚀 快速开始

Windows TTS MCP 服务器是用于在 Claude Desktop 中将文本转换为语音的 MCP（模型上下文协议）服务器。它借助 PowerShell 调用 Windows 的内置语音 API，提供稳定且快速的 TTS 功能。

✨ 主要特性

🎵 稳定的 TTS：基于 Windows PowerShell，确保线程安全。
⚡ 快速响应：支持后台播放，实现即时响应。
🎛️ 多样选项：可调节语音速度和音量。
⏹️ 完全控制：支持暂停播放、强制终止和状态检查。
🚨 紧急功能：可实现系统全局静音。
📦 便捷安装：通过 uvx 一键安装并运行。

📦 安装指南

使用 uvx 运行（推荐）

# 运行程序包
uvx windows-tts-mcp

# 开发模式
uvx --from . tts-dev

# 直接从 GitHub 运行（未来支持）
uvx --from git+https://github.com/yourusername/windows-tts-mcp windows-tts-mcp

本地开发

# 克隆仓库
git clone https://github.com/yourusername/windows-tts-mcp
cd windows-tts-mcp

# 本地运行
uvx --from . windows-tts-mcp

# 开发模式
uvx --from . tts-dev

💻 使用示例

在 Claude Desktop 中配置

在 Claude Desktop 的配置文件中添加以下内容：

{
  "mcpServers": {
    "windows-tts": {
      "command": "uvx",
      "args": ["--from", "D:\\MCP\\windows_tts_mcp", "windows-tts-mcp"]
    }
  }
}

配置文件位置：

Windows：%APPDATA%\\Claude\\claude_desktop_config.json
macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Linux：~/.config/claude/claude_desktop_config.json

语音播放操作

在 Claude Desktop 中按以下方式请求：

基础语音播放

"请朗读这段文本"
"请用语音播放以下内容"
"请用语音播放回复内容"

速度调节

"快速朗读：[文本]"
"慢速朗读：[文本]"
"小声朗读：[文本]"

播放控制

"请停止语音播放"
"请检查 TTS 状态"
"请强制终止所有语音播放"
"请紧急静音"（系统全局静音）

工具列表

| 工具 | 说明 | 使用示例 | |------|------|----------| | speak | 基础语音播放 | "请朗读这段文本" | | speak_fast | 快速播放 | "快速朗读" | | speak_slow | 慢速播放 | "慢速朗读" | | speak_quiet | 小声播放 | "小声朗读" | | speak_short | 短文本播放（100 字以内） | "简短说明" | | stop_speech | 停止语音播放 | "请停止语音" | | kill_all_tts | 强制终止所有 TTS 播放 | "终止所有语音" | | get_tts_status | 检查播放状态 | "检查语音状态" | | emergency_silence | 紧急静音 | "紧急静音" | | test_tts | 系统测试 | "TTS 测试" |

🔧 技术细节

系统要求

操作系统：Windows 10/11
Python：3.11 及以上版本
PowerShell：5.0 及以上版本（Windows 系统默认包含）
其他：Windows 语音平台（系统默认包含）

架构

Claude Desktop
    ↓ (MCP 协议)
Windows TTS MCP 服务器
    ↓ (子进程)
PowerShell
    ↓ (System.Speech)
Windows 语音 API
    ↓
音频输出

特点

线程安全：每个 TTS 请求在独立线程中处理。
进程管理：跟踪并控制所有正在运行的 TTS 进程。
错误处理：对超时和异常情况进行稳健处理。
资源清理：自动清理已完成的进程。

📚 详细文档

问题解决

无语音输出

检查 Windows 音频

# 在 PowerShell 中直接测试
Add-Type -AssemblyName System.Speech
$synth = New-Object System.Speech.Synthesis.SpeechSynthesizer
$synth.Speak("测试")

检查音量设置
- 在 Windows 音量混合器中检查 PowerShell 的音量。
- 检查系统默认音频设备设置。
检查语音平台
- 打开 Windows 设置 → 时间和语言 → 语音。
- 检查语音识别语言设置。

进程残留

# 强制清理
uvx windows-tts-mcp
# 在 Claude 中执行 "请强制终止所有 TTS 播放"

开发

项目结构

windows-tts-mcp/
├── pyproject.toml          # 包配置
├── README.md               # 本文件
├── windows_tts_mcp/        # 主包
│   ├── __init__.py
│   └── main.py            # TTS 服务器代码
├── .gitignore
└── uv.lock

开发环境设置

# 克隆仓库
git clone https://github.com/yourusername/windows-tts-mcp
cd windows-tts-mcp

# 使用 uv 安装依赖
uv sync

# 以开发模式运行
uvx --from . tts-dev

贡献代码

分叉此仓库。
创建新分支 (git checkout -b feature/amazing-feature)。
提交更改 (git commit -m '添加出色的功能')。
将分支推送到远程仓库 (git push origin feature/amazing-feature)。
发起拉取请求。

📄 许可证

本项目遵循 MIT 许可证分发。详细信息请参考 LICENSE 文件。

🙏 致谢

Anthropic - 开发了 Claude 和 MCP。
Model Context Protocol - 提供了 MCP 标准。
uv - 现代 Python 包管理工具。

🔗 相关链接

为 Claude Desktop 用户精心打造 ❤️

windows_tts_mcp