@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):

{
  "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

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