Skip to main content
Glama

Velma MCP

Velma MCP

License: MIT Python 3.10+ 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

  1. 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.

  2. Install uv. It needs Python 3.10 or newer.

  3. 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-mcp

Working 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 --> E

The 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.wav a synthetic voice?"

  • "Does track.mp3 sound like AI-generated music?"

  • "Redact personal details from interview.wav."

  • "Transcribe meeting.mp3 with speakers and emotion."

  • "Summarise the support call case-42.wav and list the topics."

  • "Which language is field-note.mp3 in, 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

detect_synthetic_voice(file_path)

Frame-by-frame deepfake check. Returns a summary (frame counts, share of speech marked synthetic, mean confidences) and the raw frames.

Deepfake Detection

detect_ai_music(file_path)

Returns primary_verdict (ai-vocal-music, ai-instrumental, not-ai-music), vocal and instrumental AI percentages, and windows.

AI Music Detection

redact_audio(file_path, language?, speaker_diarization?)

Returns the redacted transcript, utterances and silenced ranges, plus the redacted MP3 as a file, a resource, or both.

PII/PHI Redaction

transcribe_audio(file_path, speaker_diarization?, emotion_signal?, accent_signal?, deepfake_signal?, pii_phi_tagging?, language?)

Returns text and utterances with the signals you ask for.

Transcription

analyze_conversation(file_path, config?)

Velma Triage: summary, topics, conversation type, behaviours. config is default or a JSON BatchConfig.

Velma Triage

detect_emotion(file_path)

One emotion label for the file plus a label per time window.

Emotion Detection

detect_accent(file_path)

One accent label for the file plus a label per time window.

Accent Detection

detect_language(file_path)

Spoken language name, ISO 639-1 code and confidence. Analyses the first 30 seconds.

Language Detection

detect_audio_events(file_path)

Probabilities for non-speech sound events (applause, dog bark, glass shattering and more) and the top event.

Audio Event Detection

classify_music_speech(file_path)

Music or speech, with percentages and frame-level probabilities. Not an AI-music check.

Music Detection

transcribe_english_fast(file_path, speaker_diarization?, time_stamps?, medical_domain?)

Fast English transcript with optional word timings, speaker turns and medical term correction.

English Fast Transcription

transcribe_multilingual_fast(file_path, language?)

Fast multilingual transcript and the language it is in. No diarization or word timings.

Multilingual Fast Transcription

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/.

Chat: deepfake check with detect_synthetic_voice

Chat: redaction with redact_audio

Chat: AI music check with detect_ai_music

Chat: transcribe_audio and analyze_conversation

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

VELMA_API_KEY

none, required

Your Velma API key. Sent only to Modulate in the X-API-Key header.

VELMA_MCP_BASE_PATH

~/Desktop

Tools may only read files inside this folder. Relative paths are resolved against it.

VELMA_MCP_OUTPUT_MODE

files

files, resources or both. Only affects redacted audio.

VELMA_API_BASE_URL

https://platform.modulate.ai

API base URL.

Output modes (redaction only)

  • files: saves <VELMA_MCP_BASE_PATH>/velma-output/<name>-redacted-<id>.mp3 and returns redacted_audio_path. Never overwrites.

  • resources: serves the MP3 as an MCP resource velma://redacted/<id> (audio/mpeg) and returns redacted_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

Velma rejected the API key (401)

The key is missing or wrong. Check VELMA_API_KEY in the client config.

file_path is outside the allowed folder

Move the file under VELMA_MCP_BASE_PATH or change that variable.

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 browser

Most 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.

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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP 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 npm
      4
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      A 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.
      22
      17 PyPI
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for whisper-based transcription and translation, supporting local stdio and remote HTTP transports with file workflow safety.
      -