@vocametrix/mcp-server

Official Model Context Protocol server for the Vocametrix voice analysis API.

Gives any MCP-compatible AI assistant (Claude Desktop, Cursor, Cline, etc.) direct access to clinical voice metrics, pronunciation assessment, speech transcription, and AI-powered therapy planning.

Quick start

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

config.json

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

Get an API key at vocametrix.com/registration. Free trial: 5 minutes of analysis.

Tools

Voice quality (acoustic)

Tool	Description
`vocametrix_avqi`	Acoustic Voice Quality Index (AVQI) — overall dysphonia severity
`vocametrix_dsi`	Dysphonia Severity Index (DSI)
`vocametrix_cpp_cpps`	Cepstral Peak Prominence — breathiness, hoarseness
`vocametrix_hnr`	Harmonics-to-Noise Ratio (multi-band)
`vocametrix_jitter_shimmer`	Period and amplitude perturbation
`vocametrix_vrp`	Voice Range Profile
`vocametrix_prosody_similarity`	Prosody similarity between two utterances

Advanced voice analysis

Tool	Description
`vocametrix_spectral`	Spectral tilt, slope, and formant energy
`vocametrix_formants`	Formant frequencies F1–F4
`vocametrix_sz_ratio`	S/Z phonation ratio
`vocametrix_gne`	Glottal-to-Noise Excitation
`vocametrix_h1h2`	H1–H2 harmonic difference
`vocametrix_abi`	Acoustic Breathiness Index
`vocametrix_voice_dynamics`	Dynamic range and fundamental frequency statistics

Ingestion utilities

Tool	Description
`vocametrix_upload_audio`	Upload a WAV file (base64) → returns a stable blobUrl
`vocametrix_ingest_url`	Ingest a public HTTPS WAV URL → returns a stable blobUrl

Speech and pronunciation

Tool	Description
`vocametrix_assess_pronunciation`	Phoneme-level pronunciation scoring
`vocametrix_assess_pronunciation_pitch`	Pronunciation + pitch analysis combined
`vocametrix_transcribe`	Streaming ASR transcription with progress
`vocametrix_tts`	Text-to-speech synthesis
`vocametrix_tts_timing`	TTS with word-level timing data

Audio measures

Tool	Description
`vocametrix_sound_level`	dB SPL and intensity statistics
`vocametrix_egemaps`	Extended Geneva Minimalistic Acoustic Parameter Set
`vocametrix_phoneme_detection`	Phoneme presence/absence detection
`vocametrix_classify_stuttering`	Dysfluency classification

AI agents

Tool	Description
`vocametrix_agent_interpret_metrics`	Clinical interpretation of voice metrics
`vocametrix_agent_exercises`	Personalized voice/speech exercise generation
`vocametrix_agent_word_list`	Target word list generation for therapy
`vocametrix_agent_therapist_chat`	Conversational AI speech-language therapist
`vocametrix_agent_french_ipa`	French text → IPA phonetic transcription
`vocametrix_agent_spell`	Spelling correction agent
`vocametrix_agent_syntax`	Syntax checking agent
`vocametrix_agent_vocabulary_tutor`	Vocabulary tutoring agent
`vocametrix_agent_adaptive_exercise`	Adaptive exercise generation

Therapy planning

Tool	Description
`vocametrix_generate_therapy_plan`	Generate an AI therapy plan
`vocametrix_get_therapy_status`	Poll therapy plan generation status
`vocametrix_get_therapy_result`	Fetch completed therapy plan
`vocametrix_approve_therapy_plan`	Approve a therapy plan

Workflow tools

Tool	Description
`vocametrix_full_voice_assessment`	Parallel AVQI + CPP + HNR + jitter/shimmer + spectral
`vocametrix_batch_pronunciation`	Assess a folder of WAV files
`vocametrix_full_therapy_workflow`	Generate → poll → fetch → approval flow

Resources

vocametrix://docs/api — API quick reference (auth, rate limits, audio requirements, error codes)
vocametrix://thresholds/{metric} — Clinical reference thresholds for avqi, dsi, cpp, hnr, jitter-shimmer, gne

Prompts

interpret_voice_assessment — Generate a clinical SLP-style interpretation report from assessment JSON
compare_pre_post_therapy — Quantified pre/post therapy narrative with metric-by-metric comparison
generate_session_report — SOAP-format progress note from pronunciation assessment data

Audio requirements

Format: WAV (16-bit PCM recommended)
Sustained vowel tasks: 3+ seconds of /a/ phonation
Connected speech tasks: 5–30 seconds of read passage
Minimum sampling rate: 16 kHz

How to pass audio to a tool

The audioPath parameter accepts several input types, but which ones are valid depends on how the MCP server is running:

Input	Hosted / remote server	Stdio / local server (`npx`, Claude Desktop)
`https://...` blobUrl from `vocametrix_upload_audio`	✅ recommended	✅
Public `https://...` URL to a WAV file	✅	✅
Public URL via `vocametrix_ingest_url` → returned blobUrl	✅ recommended for URL inputs	✅
`data:audio/wav;base64,...` data URL	✅	✅
Raw base64 string (≥ 512 chars)	✅	✅
Absolute local path (`/home/...`, `C:\...`)	❌ rejected	⚠️ requires `VOCAMETRIX_MCP_LOCAL_FS=1`

For chat clients that attach audio in the conversation (Claude.ai web/mobile, etc.), the LLM cannot pass an absolute path to a hosted server — it must call vocametrix_upload_audio first with the file content base64-encoded, then pass the returned blobUrl as audioPath to any analysis tool. The MCP descriptions guide the LLM toward this workflow automatically.

For stdio/local deployments where the MCP runs on the user's own machine, set VOCAMETRIX_MCP_LOCAL_FS=1 to allow analysis tools to read absolute local paths directly — convenient for batch processing of files already on disk.

Environment variables

Variable	Required	Description
`VOCAMETRIX_API_KEY`	Yes	Your Vocametrix API key
`VOCAMETRIX_MCP_LOCAL_FS`	No	Set to `1` to allow analysis tools to read absolute local file paths (stdio/local deployments only). Default off — local paths are rejected with an actionable error so chat clients are pushed toward the `vocametrix_upload_audio` → `blobUrl` workflow.

Development

bash

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

MCP Registry

Listed in the official MCP Registry under io.github.pmarmaroli/vocametrix-mcp. Available for one-click installation in MCP-compatible clients (Claude Desktop, Cursor, Zed, Windsurf, and more).

Related projects

The Vocametrix ecosystem:

📘 Vocametrix API documentation — full reference for the underlying REST API powering this MCP server.
📐 OpenAPI 3.1 specification — machine-readable schema for all 48 endpoints.
🐍 vocametrix-python — official Python SDK if you want direct API access from Python (pip install vocametrix).
🟦 vocametrix-js — official TypeScript / JavaScript SDK used internally by this MCP server (npm install vocametrix).

License

MIT — see LICENSE