{
  "markdown": "# @vocametrix/mcp-server\n\n[![smithery badge](https://smithery.ai/badge/patrick-marmaroli/vocametrix)](https://smithery.ai/servers/patrick-marmaroli/vocametrix)\n\nOfficial [Model Context Protocol](https://modelcontextprotocol.io) server for the [Vocametrix](https://www.vocametrix.com) voice analysis API.\n\nGives 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.\n\n## Quick start\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"vocametrix\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vocametrix/mcp-server\"],\n      \"env\": {\n        \"VOCAMETRIX_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\nGet an API key at [vocametrix.com/registration](https://www.vocametrix.com/registration). Free trial: 5 minutes of analysis.\n\n## Tools\n\n### Voice quality (acoustic)\n| Tool | Description |\n|------|-------------|\n| `vocametrix_avqi` | Acoustic Voice Quality Index (AVQI) — overall dysphonia severity |\n| `vocametrix_dsi` | Dysphonia Severity Index (DSI) |\n| `vocametrix_cpp_cpps` | Cepstral Peak Prominence — breathiness, hoarseness |\n| `vocametrix_hnr` | Harmonics-to-Noise Ratio (multi-band) |\n| `vocametrix_jitter_shimmer` | Period and amplitude perturbation |\n| `vocametrix_vrp` | Voice Range Profile |\n| `vocametrix_prosody_similarity` | Prosody similarity between two utterances |\n\n### Advanced voice analysis\n| Tool | Description |\n|------|-------------|\n| `vocametrix_spectral` | Spectral tilt, slope, and formant energy |\n| `vocametrix_formants` | Formant frequencies F1–F4 |\n| `vocametrix_sz_ratio` | S/Z phonation ratio |\n| `vocametrix_gne` | Glottal-to-Noise Excitation |\n| `vocametrix_h1h2` | H1–H2 harmonic difference |\n| `vocametrix_abi` | Acoustic Breathiness Index |\n| `vocametrix_voice_dynamics` | Dynamic range and fundamental frequency statistics |\n\n### Ingestion utilities\n| Tool | Description |\n|------|-------------|\n| `vocametrix_upload_audio` | Upload a WAV file (base64) → returns a stable blobUrl |\n| `vocametrix_ingest_url` | Ingest a public HTTPS WAV URL → returns a stable blobUrl |\n\n### Speech and pronunciation\n| Tool | Description |\n|------|-------------|\n| `vocametrix_assess_pronunciation` | Phoneme-level pronunciation scoring |\n| `vocametrix_assess_pronunciation_pitch` | Pronunciation + pitch analysis combined |\n| `vocametrix_transcribe` | Streaming ASR transcription with progress |\n| `vocametrix_tts` | Text-to-speech synthesis |\n| `vocametrix_tts_timing` | TTS with word-level timing data |\n\n### Audio measures\n| Tool | Description |\n|------|-------------|\n| `vocametrix_sound_level` | dB SPL and intensity statistics |\n| `vocametrix_egemaps` | Extended Geneva Minimalistic Acoustic Parameter Set |\n| `vocametrix_phoneme_detection` | Phoneme presence/absence detection |\n| `vocametrix_classify_stuttering` | Dysfluency classification |\n\n### AI agents\n| Tool | Description |\n|------|-------------|\n| `vocametrix_agent_interpret_metrics` | Clinical interpretation of voice metrics |\n| `vocametrix_agent_exercises` | Personalized voice/speech exercise generation |\n| `vocametrix_agent_word_list` | Target word list generation for therapy |\n| `vocametrix_agent_therapist_chat` | Conversational AI speech-language therapist |\n| `vocametrix_agent_french_ipa` | French text → IPA phonetic transcription |\n| `vocametrix_agent_spell` | Spelling correction agent |\n| `vocametrix_agent_syntax` | Syntax checking agent |\n| `vocametrix_agent_vocabulary_tutor` | Vocabulary tutoring agent |\n| `vocametrix_agent_adaptive_exercise` | Adaptive exercise generation |\n\n### Therapy planning\n| Tool | Description |\n|------|-------------|\n| `vocametrix_generate_therapy_plan` | Generate an AI therapy plan |\n| `vocametrix_get_therapy_status` | Poll therapy plan generation status |\n| `vocametrix_get_therapy_result` | Fetch completed therapy plan |\n| `vocametrix_approve_therapy_plan` | Approve a therapy plan |\n\n### Workflow tools\n| Tool | Description |\n|------|-------------|\n| `vocametrix_full_voice_assessment` | Parallel AVQI + CPP + HNR + jitter/shimmer + spectral |\n| `vocametrix_batch_pronunciation` | Assess a folder of WAV files |\n| `vocametrix_full_therapy_workflow` | Generate → poll → fetch → approval flow |\n\n## Resources\n\n- `vocametrix://docs/api` — API quick reference (auth, rate limits, audio requirements, error codes)\n- `vocametrix://thresholds/{metric}` — Clinical reference thresholds for `avqi`, `dsi`, `cpp`, `hnr`, `jitter-shimmer`, `gne`\n\n## Prompts\n\n- `interpret_voice_assessment` — Generate a clinical SLP-style interpretation report from assessment JSON\n- `compare_pre_post_therapy` — Quantified pre/post therapy narrative with metric-by-metric comparison\n- `generate_session_report` — SOAP-format progress note from pronunciation assessment data\n\n## Audio requirements\n\n- Format: WAV (16-bit PCM recommended)\n- Sustained vowel tasks: 3+ seconds of /a/ phonation\n- Connected speech tasks: 5–30 seconds of read passage\n- Minimum sampling rate: 16 kHz\n\n### How to pass audio to a tool\n\nThe `audioPath` parameter accepts several input types, but **which ones are valid depends on how the MCP server is running**:\n\n| Input | Hosted / remote server | Stdio / local server (`npx`, Claude Desktop) |\n|---|---|---|\n| `https://...` blobUrl from `vocametrix_upload_audio` | ✅ recommended | ✅ |\n| Public `https://...` URL to a WAV file | ✅ | ✅ |\n| Public URL via `vocametrix_ingest_url` → returned blobUrl | ✅ recommended for URL inputs | ✅ |\n| `data:audio/wav;base64,...` data URL | ✅ | ✅ |\n| Raw base64 string (≥ 512 chars) | ✅ | ✅ |\n| Absolute local path (`/home/...`, `C:\\...`) | ❌ rejected | ⚠️ requires `VOCAMETRIX_MCP_LOCAL_FS=1` |\n\n**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.\n\n**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.\n\n## Environment variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `VOCAMETRIX_API_KEY` | Yes | Your Vocametrix API key |\n| `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. |\n\n## Development\n\n```bash\ngit clone https://github.com/pmarmaroli/vocametrix-mcp.git\ncd vocametrix-mcp\nnpm install\nnpm run build\nnpm test            # run unit tests\nnpm run inspector   # test with MCP Inspector\n```\n\n## MCP Registry\n\nListed in the official [MCP Registry](https://registry.modelcontextprotocol.io/) under `io.github.pmarmaroli/vocametrix-mcp`. Available for one-click installation in MCP-compatible clients (Claude Desktop, Cursor, Zed, Windsurf, and more).\n\n## Related projects\n\nThe Vocametrix ecosystem:\n\n- 📘 **[Vocametrix API documentation](https://www.vocametrix.com/api-docs)** — full reference for the underlying REST API powering this MCP server.\n- 📐 **[OpenAPI 3.1 specification](https://www.vocametrix.com/openapi.json)** — machine-readable schema for all 48 endpoints.\n- 🐍 **[vocametrix-python](https://github.com/pmarmaroli/vocametrix-python)** — official Python SDK if you want direct API access from Python (`pip install vocametrix`).\n- 🟦 **[vocametrix-js](https://github.com/pmarmaroli/vocametrix-js)** — official TypeScript / JavaScript SDK used internally by this MCP server (`npm install vocametrix`).\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n",
  "bytes": 8100,
  "sha": "95aa922f048fb3e1734f1a52b8410ed4865426570286da5d71e8671c254fa8b6",
  "repo_slug": "pmarmaroli/vocametrix-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pmarmaroli_vocametrix_mcp_798f675a/readme"
}