了解如何通过 Model Context Protocol (MCP) 将 VocoType 集成到 Claude Desktop、Cursor 或其他 AI Agent 中，实现高效的本地语音转文字和音视频转录功能。

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 服务

打开 VocoType
进入 设置 → AI
找到 MCP 服务集成 区块
开启 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 流程：

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

可用工具

`transcribe_file` - 音视频转录

将音视频文件转录为文本。

输入参数:

参数	类型	必填	说明
`file_path`	string	✅	音视频文件的绝对路径

支持格式: mp4, mp3, wav, flac, aac, m4a, ogg, mkv, webm, mov

使用示例（在 Claude 对话中）:

请帮我转录这个音频文件：/Users/leilei/Downloads/meeting.mp3

响应格式:

{
  "content": [{
    "type": "text",
    "text": "转录后的完整文本..."
  }],
  "isError": false
}

错误处理

错误码	含义	解决方案
`-32602`	文件不存在	检查文件路径是否正确，使用绝对路径
`-32602`	格式不支持	确保文件为支持的音视频格式
`-32001`	未登录	打开 VocoType 完成登录
`-32002`	时长超限	免费版限制 10 分钟，请升级或使用较短文件
`-32000`	转录繁忙	等待当前转录完成后重试

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 日志获取详细错误信息

本地语音转文字MCP