Vocametrix

@vocametrix/mcp-server

适用于 Vocametrix 语音分析 API 的官方 Model Context Protocol 服务。

让任何兼容 MCP 的 AI 助手（Claude Desktop、Cursor、Cline 等）都能直接访问临床语音指标、发音评估、语音转录和 AI 驱动的治疗规划。

快速开始

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "vocametrix": {
      "command": "npx",
      "args": ["-y", "@vocametrix/mcp-server"],
      "env": {
        "VOCAMETRIX_API_KEY": "your-api-key-here"
      }
    }
  }
}

在 vocametrix.com/registration 获取 API 密钥。MCP 分析会使用已购买的 API 点数；网站订阅和试用不包含 API 调用。

Claude Code

托管服务（无需本地安装）：

claude mcp add --transport http vocametrix https://mcp.vocametrix.com/mcp --header "x-api-key: your-api-key-here"

也可以使用 npx 在本地运行：

claude mcp add vocametrix -e VOCAMETRIX_API_KEY=your-api-key-here -- npx -y @vocametrix/mcp-server

在 claude mcp add 后立即添加 --scope user，即可在所有项目中使用 Vocametrix。然后在 Claude Code 中输入 /mcp 检查连接。

ChatGPT（OAuth、API 点数）

可选的 /chatgpt/mcp 端点通过 OAuth 关联用户的 API 账户。用户在平台的授权页面批准访问；ChatGPT 获取的是可撤销令牌，而不是 API 密钥。现有的 /mcp API 密钥客户端和本地 stdio 客户端仍受支持。

请参阅 ChatGPT 设置和发布检查，了解相应的平台变更、数据库迁移、配置和测试。此集成必须先在 ChatGPT 中部署并测试，才能公开提交。

工具

语音质量（声学）

工具	描述
vocametrix_calculate_avqi	声学语音质量指数（AVQI）——总体嗓音障碍严重程度
vocametrix_calculate_dsi	嗓音障碍严重程度指数（DSI）
vocametrix_calculate_cpp	倒谱峰值突出度——气声、沙哑
vocametrix_calculate_hnr	谐噪比（多频带）
vocametrix_calculate_jitter_shimmer	周期和振幅扰动
vocametrix_calculate_voice_range_profile	音域图
vocametrix_calculate_prosody_similarity	两段话语之间的韵律相似度

高级语音分析

工具	描述
vocametrix_calculate_spectral	谱倾斜、斜率和共振峰能量
vocametrix_calculate_formants	共振峰频率 F1–F4
vocametrix_calculate_sz_ratio	S/Z 发声比
vocametrix_calculate_gne	声门噪声激励
vocametrix_calculate_h1_h2	H1–H2 谐波差
vocametrix_calculate_abi	声学气声指数
vocametrix_calculate_voice_dynamics	动态范围和基频统计
vocametrix_measure_ddk	轮替运动（pa-ta-ka）：音节速率、规律性、加速度；适用于 65-86 岁人群的 Pierce 2013 常模

数据导入工具

工具	描述
vocametrix_upload_audio	上传 WAV 文件（base64）→ 返回稳定的 blobUrl
vocametrix_ingest_url	导入公开的 HTTPS WAV URL → 返回稳定的 blobUrl

语音和发音

工具	描述
vocametrix_assess_pronunciation	音素级发音评分
vocametrix_assess_pronunciation_with_pitch	发音和音高联合分析
vocametrix_transcribe_audio	带进度信息的流式 ASR 转录
vocametrix_synthesize_speech	文本转语音合成

音频测量

工具	描述
vocametrix_measure_sound_level	一段时间内未经校准的 dB 声级
vocametrix_extract_egemaps	日内瓦极简声学参数集 GeMAPS v01b（62 项特征）
vocametrix_detect_phonemes	法语音素检测，包含置信度分数和时间戳
vocametrix_classify_stuttering	言语不流畅分类

AI Agent

工具	描述
vocametrix_interpret_voice_metrics	对声音指标进行临床解读
vocametrix_generate_exercises	个性化声音／言语练习生成
vocametrix_generate_word_list	生成治疗用目标词列表
vocametrix_chat_speech_therapist	对话式 AI 言语语言治疗师
vocametrix_convert_french_to_ipa	法语文本 → IPA 音标转写
vocametrix_interpret_spelling_attempt	拼写纠正 Agent
vocametrix_check_syntax	语法检查 Agent
vocametrix_vocabulary_tutor	词汇辅导 Agent
vocametrix_adapt_exercise	自适应练习生成

治疗规划

未在 ChatGPT 端点（/chatgpt/mcp）上发布：这些工具需要患者标识符和临床病史，而 ChatGPT 应用指南将其视为受保护的健康信息。它们仍可通过 stdio 和 /mcp 使用。

工具	描述
vocametrix_generate_therapy_plan	生成 AI 治疗计划
vocametrix_get_therapy_status	查询治疗计划生成状态
vocametrix_get_therapy_result	获取已完成的治疗计划
vocametrix_approve_therapy_plan	批准治疗计划

工作流工具

工具	描述
vocametrix_full_voice_assessment	并行进行 AVQI + CPP + HNR + jitter/shimmer + 频谱分析
vocametrix_batch_pronunciation	评估一个 WAV 文件文件夹。读取服务自身的文件系统，因此仅在 stdio／本地模式（VOCAMETRIX_MCP_LOCAL_FS=1）下注册——托管服务上不可用
vocametrix_full_therapy_workflow	生成 → 查询 → 获取 → 审批流程

资源

• vocametrix://docs/api — API 快速参考（身份验证、速率限制、音频要求、错误代码）
• vocametrix://recording-guide — 每种工具的录音规范（持续元音、带语言专属参考句的连贯语音、滑音、持续发 /s/ 和 /z/）
• vocametrix://thresholds/{metric} — avqi、dsi、cpp、hnr、jitter-shimmer、gne 的临床参考阈值

提示词

• interpret_voice_assessment — 根据评估 JSON 生成临床 SLP 风格解读报告
• compare_pre_post_therapy — 按指标逐项比较并量化治疗前后的情况
• generate_session_report — 根据发音评估数据生成 SOAP 格式的进展记录

音频要求

• 格式：WAV（推荐 16 位 PCM）
• 持续元音任务：发 /a/ 音至少 3 秒
• 连贯语音任务：朗读 5–30 秒的段落
• 最低采样率：16 kHz

如何向工具传递音频

audioPath 参数接受多种输入类型，但哪些类型有效取决于 MCP 服务的运行方式：

输入	托管／远程服务	Stdio／本地服务（npx、Claude Desktop）
来自 vocametrix_upload_audio 的 https://... blobUrl	✅ 推荐	✅
指向 WAV 文件的公开 https://... URL	✅	✅
通过 vocametrix_ingest_url 获取的公开 URL → 返回的 blobUrl	✅ 推荐用于 URL 输入	✅
data:audio/wav;base64,... 数据 URL	✅	✅
原始 base64 字符串（≥ 512 个字符）	✅	✅
绝对本地路径（/home/...、C:\...）	❌ 不接受	⚠️ 需要设置 VOCAMETRIX_MCP_LOCAL_FS=1

对于在对话中附加音频的聊天客户端（Claude.ai 网页版／移动版等），大模型无法向托管服务传递绝对路径——必须先使用文件内容的 base64 编码调用 vocametrix_upload_audio，然后将返回的 blobUrl 作为 audioPath 传递给任意分析工具。MCP 描述会自动引导大模型采用此工作流。

对于 MCP 在用户自己的计算机上运行的 stdio／本地部署，设置 VOCAMETRIX_MCP_LOCAL_FS=1，即可允许分析工具直接读取绝对本地路径，方便批量处理磁盘上已有的文件。

环境变量

变量	必需	描述
VOCAMETRIX_API_KEY	是	你的 Vocametrix API 密钥
VOCAMETRIX_MCP_LOCAL_FS	否	设置为 1，允许分析工具读取绝对本地文件路径（仅限 stdio／本地部署）。默认关闭——本地路径会被拒绝，并返回可操作的错误提示，促使聊天客户端采用 vocametrix_upload_audio → blobUrl 工作流。
VOCAMETRIX_MCP_ALLOW_PRIVATE_HOSTS	否	设置为 1，允许获取主机解析到私有、环回或链路本地地址的音频 URL（例如局域网文件服务器）。默认关闭，包括 stdio／本地模式：MCP 工具的调用方是大模型，而读取了恶意页面的大模型可能会被诱导，将这些工具指向你自己的网络。

开发

git clone https://github.com/Vocametrix/vocametrix-mcp.git
cd vocametrix-mcp
npm install
npm run build
npm test            # run unit tests
npm run inspector   # test with MCP Inspector

MCP 注册表

已在官方 MCP 注册表中列出，条目为 io.github.pmarmaroli/vocametrix-mcp。可在兼容 MCP 的客户端（Claude Desktop、Cursor、Zed、Windsurf 等）中一键安装。

相关项目

Vocametrix 生态系统：

• 📘 Vocametrix API 文档 — 本 MCP 服务所依赖的 REST API 完整参考。
• 📐 OpenAPI 3.1 规范 — 全部 49 个端点的机器可读架构。
• 🐍 vocametrix-python — 官方 Python SDK，可从 Python 直接访问 API（pip install vocametrix）。
• 🟦 vocametrix-js — 本 MCP 服务内部使用的官方 TypeScript／JavaScript SDK（npm install vocametrix）。

许可证

MIT — 详见 LICENSE