Velma MCP
OfficialThis server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.

Velma MCP
A local Model Context Protocol server for Modulate's Velma voice AI. It lets MCP clients such as Claude Desktop, Claude Code, Cursor and Windsurf check a recording for deepfake voices or AI music, redact personal data, transcribe, detect emotion, accent, language and sound events, and analyse a conversation. Twelve tools cover the Velma batch API.
Prefer plain instructions over a running server? See the companion Velma Skills repo.
Velma is a trademark of Modulate.
Quickstart
Get a Velma API key: sign up at https://platform.modulate.ai/signup-request, then create a key on the API Keys page. New accounts get free credits.
Install uv. It needs Python 3.10 or newer.
Add the server to your MCP client. Claude Desktop (
claude_desktop_config.json), Cursor (~/.cursor/mcp.json) and Windsurf (~/.codeium/windsurf/mcp_config.json) use the same block:
{
"mcpServers": {
"velma": {
"command": "uvx",
"args": ["--from", "git+https://github.com/modulate-ai/velma-mcp", "velma-mcp"],
"env": {
"VELMA_API_KEY": "<your-key>",
"VELMA_MCP_BASE_PATH": "/Users/you/Audio"
}
}
}
}Claude Code:
claude mcp add velma -e VELMA_API_KEY=<your-key> -e VELMA_MCP_BASE_PATH=/Users/you/Audio -- uvx --from "git+https://github.com/modulate-ai/velma-mcp" velma-mcpWorking from a checkout instead? Replace "args" with ["--from", "/absolute/path/to/velma-mcp", "velma-mcp"], or in Claude Code use -- uvx --from /absolute/path/to/velma-mcp velma-mcp. In claude mcp add, put the server name before the -e flags. Other clients take the same command, args and env values in their own config format.
The server runs locally as a stdio process that your client starts, so nothing needs to be hosted.
Related MCP server: fsext-mcp-server-python
How it works
%%{init: {"flowchart": {"nodeSpacing": 24, "rankSpacing": 36, "padding": 6, "wrappingWidth": 260, "htmlLabels": true}, "themeVariables": {"fontSize": "13px"}}}%%
flowchart LR
classDef client fill:#dbeafe,stroke:#2563eb,color:#0f172a
classDef local fill:#e5e7eb,stroke:#4b5563,color:#0f172a
classDef velma fill:#ede9fe,stroke:#7c3aed,color:#0f172a
A["<b>MCP client</b><br/>Claude, Cursor, Windsurf"]:::client
B["<b>velma-mcp</b><br/>local stdio process<br/>12 tools"]:::local
C["<b>File sandbox</b><br/>VELMA_MCP_BASE_PATH"]:::local
D["<b>Velma batch API</b><br/>platform.modulate.ai"]:::velma
E["<b>Result</b><br/>JSON, redacted MP3<br/>as file or resource"]:::client
A -->|"tool call over stdio"| B
B -->|"path check"| C
C -->|"POST upload_file<br/>X-API-Key"| D
D --> EThe client starts the server and calls its tools over stdio. Each tool resolves the file path inside VELMA_MCP_BASE_PATH, uploads the file to the Velma endpoint and returns a short, structured result. The API key stays on your machine, is sent only to Modulate in the X-API-Key header and is scrubbed from error text.
Example prompts
"Is
call.wava synthetic voice?""Does
track.mp3sound like AI-generated music?""Redact personal details from
interview.wav.""Transcribe
meeting.mp3with speakers and emotion.""Summarise the support call
case-42.wavand list the topics.""Which language is
field-note.mp3in, and what is the emotional tone?"
Each call uploads the file to Modulate's API and uses credits.
Tools
Tool | What it does | API reference |
| Frame-by-frame deepfake check. Returns a summary (frame counts, share of speech marked synthetic, mean confidences) and the raw frames. | |
| Returns | |
| Returns the redacted transcript, utterances and silenced ranges, plus the redacted MP3 as a file, a resource, or both. | |
| Returns text and utterances with the signals you ask for. | |
| Velma Triage: summary, topics, conversation type, behaviours. | |
| One emotion label for the file plus a label per time window. | |
| One accent label for the file plus a label per time window. | |
| Spoken language name, ISO 639-1 code and confidence. Analyses the first 30 seconds. | |
| Probabilities for non-speech sound events (applause, dog bark, glass shattering and more) and the top event. | |
| Music or speech, with percentages and frame-level probabilities. Not an AI-music check. | |
| Fast English transcript with optional word timings, speaker turns and medical term correction. | |
| Fast multilingual transcript and the language it is in. No diarization or word timings. |
Detection results are probability signals, not proof. Spot-check redacted output before sharing it. medical_domain corrects misheard clinical terms in English audio and adds some latency. The docs give no accuracy figure, so test it on your own audio.
In action
Example chats illustrated from real runs against the live API with the clips in fixtures/.




Example result
detect_synthetic_voice on a text-to-speech clip (trimmed, real run):
{"filename": "synthetic-1.wav", "duration_ms": 9334,
"summary": {"frame_counts": {"synthetic": 3, "non-synthetic": 0, "no-content": 0},
"synthetic_share_of_non_silent_frames": 1.0,
"mean_confidence_synthetic_frames": 0.972,
"majority_verdict": "synthetic"},
"frames": [{"start_time_ms": 0, "end_time_ms": 4000, "verdict": "synthetic", "confidence": 0.9717}]}On a human reading (real-2.wav) all 3 frames came back non-synthetic, mean confidence 0.917.
Environment variables
Variable | Default | Meaning |
| none, required | Your Velma API key. Sent only to Modulate in the |
|
| Tools may only read files inside this folder. Relative paths are resolved against it. |
|
|
|
|
| API base URL. |
Output modes (redaction only)
files: saves<VELMA_MCP_BASE_PATH>/velma-output/<name>-redacted-<id>.mp3and returnsredacted_audio_path. Never overwrites.resources: serves the MP3 as an MCP resourcevelma://redacted/<id>(audio/mpeg) and returnsredacted_audio_resource. The last 10 are kept in memory.both: does both.
Security
Tools read local files only inside
VELMA_MCP_BASE_PATH...escapes, absolute paths outside it, and symlinks pointing outside are rejected.Your API key stays on your machine. It is not logged and is scrubbed from error text.
Audio leaves your machine. Every tool uploads the file to Modulate's API. Per Modulate's FAQ, self-service (pay-as-you-go) accounts are enrolled in the Model Improvement Program, so audio may be used to train and improve models. To opt out, contact sales@modulate.ai. Do not send audio you may not share.
Logs go to stderr only: tool name and HTTP status. No audio, no key.
Limits
Max file size 100 MB. Empty files are rejected.
Concurrency: 3 requests at a time in this server (the API default is 3 per model). No automatic retries.
Formats: synthetic voice, AI music, language detection, music and speech detection and English fast transcription accept 96 extensions (for example wav, mp3, flac, m4a, ogg, opus, aac). Redaction, transcription, conversation analysis, emotion, accent, audio events and multilingual fast transcription accept aac, aiff, flac, mov, mp3, mp4, ogg, opus, wav, webm.
Deepfake detection: 4 to 60 second clips are best. Under 0.5 seconds the API returns 422.
Streaming (WebSocket) is not covered. For a working streaming example, see velma-browser-streaming-example.
Troubleshooting
Message | Meaning and fix |
| The key is missing or wrong. Check |
| Move the file under |
429 with "Concurrent request limit" | Too many calls at once. Try again shortly. |
429 with "Insufficient credits" or "Monthly usage limit" | Do not retry. Add credits or wait for the next cycle. |
422 on deepfake detection | The audio is under 0.5 seconds. |
More causes and fixes are in the Velma troubleshooting guide. For limits and keys, see authentication and rate limits. Questions go to Modulate support.
Development
uv sync
uv run pytest # live tests are skipped without a key
VELMA_API_KEY=... uv run pytest # also runs the live tests against fixtures/
npx @modelcontextprotocol/inspector uvx --from . velma-mcp # try the tools in a browserMost tests use mocked responses. Some data in tests/data/ is derived from the OpenAPI spec examples and some in tests/data/real/ was captured from the live API. tests/test_live.py expects synthetic-1.wav, real-1.wav, music-1.wav and pii-speech.wav in fixtures/. Sources and licences: SOURCES.md. To add a tool, see CONTRIBUTING.md.
Links
Licence
MIT. Copyright (c) 2026 Modulate AI. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted MCP tools for FFmpeg-style video and audio processing through FFMPEG API.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
MCP server for the FFmpeg Micro video transcoding API — create, monitor, download transcodes.
Related MCP Servers
AlicenseNot gradedqualityBmaintenanceMCP server exposing the full CutPro v1 API as 34 tools for AI clients — analyze videos, submit clipping jobs, manage clips, render, and publish posts. Supports stdio, Streamable HTTP, and OAuth 2.1.805 npm4MIT- AlicenseCqualityCmaintenanceA full-featured secure MCP server for local file system operations, with built-in image processing, OCR and media tools. Fully compliant with the official Model Context Protocol specification, offering standardized request/response schemas, large-file streaming I/O, multi-transport remote deployment, and comprehensive text search & replace functionality for LLM agent integration.2217 PyPIApache 2.0
- FlicenseAqualityCmaintenanceMCP server that wraps MiniMax platform APIs (speech, video, image, music, and file management) as tools over stdio, enabling natural language interaction with MiniMax's AI services.161-
- FlicenseNot gradedqualityDmaintenanceMCP server for whisper-based transcription and translation, supporting local stdio and remote HTTP transports with file workflow safety.-