VocoType MCP 使用指南

VocoType 是一款专注于隐私和效率的本地语音转文字应用。通过支持 Model Context Protocol (MCP)，它能够无缝接入各类现代 AI Agent（如 Claude Desktop、Cursor、Zed 等），让你的 AI 助手具备直接处理音视频文件的能力，实现全自动化的本地转录流。

VocoType 支持 Model Context Protocol (MCP)，允许 AI Agent（如 Claude Desktop、Cursor 等）通过标准协议调用 VocoType 的语音转文字功能。

快速开始

1. 启用 MCP 服务

1. 打开 VocoType
2. 进入 设置 → AI
3. 找到 MCP 服务集成 区块
4. 开启 MCP 服务开关

服务启动后，状态会显示为 ✅ 运行中 (端口: 36058)

2. 配置 AI 客户端

Claude Desktop 配置

编辑 Claude Desktop 配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "vocotype": {
      "url": "http://127.0.0.1:36058/message",
      "transport": "http"
    }
  }
}

重启 Claude Desktop 后，即可在对话中使用 VocoType 转录功能。

Cursor / 其他 MCP 客户端

在对应的 MCP 配置中添加：

• Server URL: http://127.0.0.1:36058/message
• Transport: HTTP (JSON-RPC 2.0)

Cherry Studio 配置

Cherry Studio 是一个支持多种现代 AI 协议的强大桌面客户端，它可以完美配合 VocoType 实现本地语音转文字 Agent 流程：

1. 打开 Cherry Studio 并进入 设置 → 扩展工具。
2. 在 MCP 服务器 区域点击 添加服务器。
3. 填入以下信息：
   • 名称: VocoType
   • 类型: HTTP
   • URL/Endpoint: http://127.0.0.1:36058/message
4. 勾选 启用 并在对话框的工具列表中选中 VocoType 即可开始使用。

可用工具

VocoType 提供的 MCP 工具采用异步模式（提交任务 -> 轮询状态 -> 获取结果），以处理长耗时的音视频转录。

1. transcribe_file - 提交转录

提交音视频文件路径，发起转录任务。

输入参数:

响应示例:

{
  "content": [{
    "type": "text",
    "text": "任务已提交，Job ID: job_123456"
  }],
  "isError": false
}

2. get_transcription_status - 查询状态

查询转录任务的状态和进度。

输入参数:

响应示例:

{
  "status": "running",
  "progress": 45
}

状态可能为：pending, running, completed, failed。

3. get_transcription_result - 获取结果

当任务状态为 completed 时，调用此工具获取最终文本。

输入参数:

异步轮询建议 (指数退避)

为减少 Token 消耗并提高效率，建议 AI 在调用时遵循 指数退避 (Exponential Backoff) 策略：

1. 初始等待：提交任务后，建议等待 5s 进行首次状态查询。
2. 状态检查：调用 get_transcription_status。如果任务仍在进行中，下一次查询间隔翻倍（如 5s -> 10s -> 20s...）。
3. 获取终态：仅在状态变为 completed 时，才调用 get_transcription_result。
4. 最大间隔：单次轮询间隔建议不超过 30s。

错误处理

API 参考

服务信息

• 协议: JSON-RPC 2.0 over HTTP
• 地址: http://127.0.0.1:36058
• 端点:
  • POST /message - MCP 消息处理
  • GET /health - 健康检查

健康检查

curl http://127.0.0.1:36058/health

响应示例：

{
  "status": "ok",
  "service": "vocotype-mcp",
  "version": "1.0.0",
  "protocol_version": "2024-11-05",
  "port": 36058
}

安全说明

• MCP 服务仅监听本地 (127.0.0.1)，无法从外部网络访问
• 请求必须包含有效的本地 Origin 头，防止 DNS rebinding 攻击
• 不支持并发转录，避免资源竞争

故障排除

服务无法启动

• 检查端口 36058 是否被占用
• 尝试重启 VocoType

AI 客户端无法连接

• 确认 MCP 服务状态显示为"运行中"
• 检查客户端配置 URL 是否正确
• 重启 AI 客户端

转录失败

• 确保 VocoType 已登录
• 检查 ASR 模型是否已下载
• 查看 VocoType 日志获取详细错误信息