---
title: "Murmur CLI & MCP Docs | Local AI Voice Automation"
description: "Generate private local voiceovers from Terminal, Codex, Claude Code, Cursor, or any MCP client with Murmur for Mac."
canonical: "https://www.murmurtts.com/docs/automation"
---
DocsAutomation CLI + MCP DOCUMENTATION

# Voice automation, *documented*.

Generate voiceovers from Terminal, or let Codex, Claude, and Cursor call Murmur directly through MCP. Installed models and saved voices stay local to your Mac.

Start installing[Explore the feature](https://www.murmurtts.com/automation)Quick start$`murmur generate --input script.txt --output narration.wav`Created`narration.wav`*· 4.2 seconds, fully on-device*

Start hereInstall the CLIFirst audio fileAgentsConnect MCPAgent workflowReferenceBatch manifestsCommands & toolsSafety & privacyTroubleshooting**Runs on your Mac**No cloud API required

01

Setup

## Install the CLI once

The CLI is a signed helper that ships inside the app. One click links it into your shell.

### Enable local automation

Open **Settings → Automation** in Murmur and turn on **Allow local automation**. Nothing outside the app can call the helper until you do.

### Install the CLI

Click **Install CLI** in the same pane. Murmur links `~/.local/bin/murmur` to the signed helper inside the app — no separate download, no package manager.

### Verify from Terminal

Run `murmur status`. If Terminal says *command not found*, add the line below to `~/.zshrc` and restart it.

```
export PATH="$HOME/.local/bin:$PATH"
```

```
murmur status
```

02

Generate

## Create your first audio file

Pass text directly, or point Murmur at a UTF-8 text or Markdown script. Output can be WAV or M4A.

```
murmur generate \
  --text "Welcome back. Today we're building a local voice workflow." \
  --voice af_bella \
  --speed 0.95 \
  --output audio/intro.wav
```

```
murmur generate \
  --input scripts/chapter-01.txt \
  --model kokoro \
  --output audio/chapter-01.m4a
```

**Preview voices in the app, or manage models from your agent.**Run `murmur models` for IDs, install with `murmur models install ID`, and choose the default with `murmur models default ID`.

03

Agents

## Connect your coding agent

MCP is the agent-facing layer over the same CLI contract. Each setup uses the helper’s absolute path, so it works without any shell PATH configuration.

### Codex

Adds Murmur to your Codex MCP config.

```
codex mcp add murmur -- /Applications/Murmur.app/Contents/Helpers/murmur mcp serve
```

### Claude Code

Registers Murmur as a user-scope stdio server.

```
claude mcp add --transport stdio --scope user murmur -- /Applications/Murmur.app/Contents/Helpers/murmur mcp serve
```

### Cursor

Goes in ~/.cursor/mcp.json, or .cursor/mcp.json for one project.

```
{
  "mcpServers": {
    "murmur": {
      "command": "/Applications/Murmur.app/Contents/Helpers/murmur",
      "args": ["mcp", "serve"]
    }
  }
}
```

04

Workflow

## Ask for the outcome, not the plumbing

Example prompt

Read `video/script.md`. Split it into intro, demo, and outro. Use Murmur to create WAV files in `video/voiceover/`, keeping one voice and pace across every scene. Don’t replace existing takes.

The agent can inspect, download, select, and remove models; inspect voices; then submit audio work and return the exact files it created. Long operations return a job ID by default, so the agent can keep working and poll `murmur_get_job` without blocking the MCP connection.

05

Projects

## Version a whole voiceover with your project

Keep a small JSON manifest beside the video script. Relative input and output paths resolve from the manifest’s folder, so the voiceover versions with the project.

```
{
  "items": [
    {
      "id": "intro",
      "text": "Here is the feature we are building today.",
      "outputPath": "audio/01-intro.wav",
      "voiceID": "af_bella",
      "speed": 0.95
    },
    {
      "id": "demo",
      "inputPath": "scripts/02-demo.txt",
      "outputPath": "audio/02-demo.wav",
      "voiceID": "af_bella"
    }
  ]
}
```

```
murmur batch --manifest video/scenes.json
```

06

Reference

## Commands & MCP tools

### CLI reference

`murmur status [--json]`Readiness and defaults`murmur models [--json]`Model IDs and install state`murmur models install ID [--detach]`Download a model`murmur models default ID`Change the default model`murmur models remove ID --confirm`Remove a downloaded model`murmur voices [--model ID] [--json]`Preset and saved voices`murmur generate …`Create one WAV or M4A`murmur batch --manifest FILE`Create multiple files`murmur jobs get ID`Read a detached job`murmur jobs cancel ID`Stop active generation`murmur mcp serve`Start the stdio MCP server

### MCP tools

`murmur_status`Check setup, license, app, and automation readiness.`murmur_list_models`See every model, capability, and install state.`murmur_list_voices`List preset voices and saved reference profiles.`murmur_install_model`Download a model as a trackable background job.`murmur_set_default_model`Choose the installed model used when model_id is omitted.`murmur_remove_model`Remove downloaded model files after explicit confirmation.`murmur_generate_speech`Queue one WAV or M4A inside the active workspace.`murmur_generate_batch`Queue a sequence of named audio files as one job.`murmur_get_job`Read progress and finished artifact paths.`murmur_cancel_job`Stop an active generation, batch, or model operation.

07

Privacy

## Local by design. Explicit by default.

**Opt-in access**

Automation starts disabled and must be enabled inside Murmur.

**One model owner**

The Mac app runs generation, so the CLI and agents do not start competing model servers.

**Workspace boundary**

MCP reads and writes only inside the directory where the agent launched it.

**No surprise overwrite**

Existing output fails safely unless you pass `--force`.

**Explicit model deletion**

Removing downloaded model files requires `confirm: true`. Bundled Kokoro cannot be removed.

**No cloud hop**

Prompts, scripts, saved voices, and generated audio remain on your Mac.

08

Help

## Troubleshooting

murmur: command not found

Run the PATH command in Install the CLI, restart Terminal, or call `/Applications/Murmur.app/Contents/Helpers/murmur` directly.

Automation is disabled

Open Murmur → Settings → Automation and turn on “Allow local automation.” Status requests still work so agents can explain what is missing.

A model is not installed

Ask the agent to call `murmur_install_model`, or run `murmur models install MODEL_ID`. Downloads stay managed by the app and report progress through the job tools.

The output already exists

Choose a new take name, remove the old file yourself, or pass --force when replacing it is intentional.

**Want the tour first?**The CLI & MCP feature page walks through what automation unlocks.[View feature](https://www.murmurtts.com/automation)