VoiceStudio MCP Setup, Lifecycle, Troubleshooting

Install

# Pick any location. The scripts in this skill default to ~/VoiceStudio if
# $OMNIVOICE_HOME is unset.
export OMNIVOICE_HOME="${HOME}/VoiceStudio"

git clone https://github.com/debpalash/VoiceStudio.git "$OMNIVOICE_HOME"
cd "$OMNIVOICE_HOME"
uv sync                                                  # ~1.6 GB venv on darwin arm64
VIRTUAL_ENV="$(pwd)/.venv" uv pip install 'mcp[cli]'     # SDK not in their lockfile yet

Any non-default install location works as long as $OMNIVOICE_HOME is set in the env that launches the MCP server.

MCP Wiring

Drop into your MCP client config (Claude Desktop, Claude Code at ~/.claude.json, Cursor, OpenClaw, etc.). Replace <OMNIVOICE_HOME> with the absolute path:

{
  "mcpServers": {
    "omnivoice": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory", "<OMNIVOICE_HOME>",
        "run", "python", "-m", "backend.mcp_server"
      ],
      "env": { "OMNIVOICE_API_URL": "http://localhost:3900" }
    }
  }
}

Restart the MCP client. The server only starts at client launch — in-session edits do not hot-reload.

Note (mcp SDK ≥ 1.10): If you see TypeError: FastMCP.__init__() got an unexpected keyword argument 'version', your VoiceStudio checkout is older than debpalash/VoiceStudio#112. Either git pull once that PR lands, or apply the 3-line patch manually: replace version="…", description=(…) with instructions=(…) in backend/mcp_server.py.

Backend Lifecycle

The MCP server needs the FastAPI backend running:

# Foreground (logs in terminal)
cd "$OMNIVOICE_HOME"
uv run uvicorn main:app --app-dir backend --host 127.0.0.1 --port 3900

# Detached, via the helper script in this skill
scripts/start-backend.sh                                  # idempotent
scripts/check-health.sh                                   # exit 0/1
scripts/stop-backend.sh                                   # graceful SIGTERM

127.0.0.1 keeps the API local-only. The project's package.json defaults to 0.0.0.0 which exposes the API on all interfaces — wider than needed for personal use.

First boot runs alembic migrations on the SQLite settings DB at <data_dir>/omnivoice.db. Idempotent — safe to re-run.

First synthesis call lazy-downloads the k2-fsa/OmniVoice model (~2.4 GB) into the HuggingFace cache. Path varies by OS:

• macOS / Linux: ~/.cache/huggingface/hub/
• Windows: %LOCALAPPDATA%\OmniVoice\hf_cache (VoiceStudio redirects via backend/core/config.py to keep the cache off the system drive root)

Cached on subsequent boots.

Idle Behavior

GET /system/info exposes idle_timeout_seconds: 900. After 15 min of no synthesis, the diffusion model is evicted from GPU memory but the FastAPI server stays up. Next call pays ~5-10 s warm-up.

Environment Variables

Troubleshooting

Clean teardown

scripts/stop-backend.sh                                   # graceful shutdown
# Uninstall: rm -rf "$OMNIVOICE_HOME" ~/.cache/huggingface/hub/models--k2-fsa--OmniVoice
# Remove the `omnivoice` entry from your MCP client config

User profiles + history live in the platform data dir (~/Library/Application Support/OmniVoice/ on macOS; ~/.local/share/VoiceStudio/ on Linux). Preserve across reinstalls if you want to keep your saved voice profiles.