MCP Server

Let Claude, Cursor, Codex, and other AI assistants search your history and trigger rewrites via the Model Context Protocol.

VivaDicta ships a Model Context Protocol (MCP) server so AI assistants - Claude Desktop, Claude Code, Cursor, Codex CLI, Zed, VS Code - can search your dictation history and trigger AI rewrites without leaving the assistant's chat interface.

What you get: Ask your assistant things like “summarise yesterday's standup” or “find the note where I talked about the Q4 roadmap and rewrite it as action items” - the agent calls VivaDicta directly and answers with your own transcriptions.

How It Works

The MCP server is the same VivaDicta.app binary, invoked with the --mcp-server flag. SwiftUI never boots; the process speaks JSON-RPC 2.0 over stdio until the client disconnects.

Read tools (search, list, get) open the SwiftData store read-only directly from disk. They work without the VivaDicta app running.
Write tools (rewrite, transcribe) route through a Unix-domain socket into the running VivaDicta app, which owns the AI provider credentials and model cache. They require the app to be open.

Install

Prerequisite: VivaDicta.app installed at /Applications/VivaDicta.app (download the DMG from vivadicta.com and drag to Applications).

Option A - Homebrew (recommended)

brew install n0an/tap/vivadicta-mcp

You get a single executable on $PATH(/opt/homebrew/bin/vivadicta-mcp) that MCP clients spawn on demand. No background daemon, no launchd plist - it's a thin shim that execs the app binary with --mcp-server.

Option B - direct path

Skip Homebrew and point your MCP client at the app binary directly. Works identically; just a longer command to register.

/Applications/VivaDicta.app/Contents/MacOS/VivaDicta --mcp-server

Connect Your Agent

Claude Code

claude mcp add --scope user vivadicta -- vivadicta-mcp

Codex CLI

codex mcp add vivadicta -- vivadicta-mcp

That writes the entry into ~/.codex/config.toml for you. Start a fresh Codex session and the vivadicta tools are available.

Prefer to edit the TOML by hand? Add this block to ~/.codex/config.toml:

[mcp_servers.vivadicta]
command = "vivadicta-mcp"

Cursor

Open Settings → MCP → Add new MCP server and add a stdio entry with command: vivadicta-mcp.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vivadicta": {
      "command": "vivadicta-mcp"
    }
  }
}

Restart Claude Desktop. The tools appear in the hammer menu.

Zed, VS Code, any other stdio MCP client

Register a stdio server with command vivadicta-mcp (or the full app-binary path for Option B). All clients that implement the MCP stdio transport work the same way.

Available Tools

Tool	Kind	Purpose
`find_transcriptions`	read	Full-text search with filters
`get_recent_transcriptions`	read	Most recent N transcriptions
`get_transcription`	read	One transcription by id or query
`get_transcription_status`	read	Poll an async job
`list_presets`	read	AI rewrite presets
`list_tags`	read	User and source tags
`list_viva_modes`	read	Per-app / per-URL profiles
`list_vocabulary`	read	Custom vocabulary words
`list_word_replacements`	read	Find-and-replace rules
`rewrite_transcription`	write	Apply a preset to a transcription
`transcribe_file`	write	Transcribe a local audio file
`transcribe_url`	write	Transcribe a YouTube URL

Example Prompts

“Show my last 5 transcriptions.”
“Find the note about the budget review - give me the full text.”
“Rewrite yesterday's call with Sam as action items.”
“Transcribe ~/Downloads/interview.m4a and summarise it.”
“What AI presets do I have? Make a new variation of my most recent note with ‘Email’.”

Privacy

The MCP server is a local process on your Mac. Nothing leaves your machine except calls your AI provider already makes during rewrites (same keys, same endpoints as the app). If you unplug your network, read tools still work.

Troubleshooting

error: VivaDicta.app not found - install the DMG from vivadicta.com to /Applications/VivaDicta.app. The shim hardcodes that path.
Write tools fail with a socket error - launch VivaDicta. Reads work headlessly; writes need the running app.
Tools don't appear in the agent - check the client's MCP log. Most clients require a restart after editing config. Verify with vivadicta-mcp (it should print the “not found” hint if the app is missing - that means the shim itself works).

VivaDicta CLI - same data, same writes, but from the shell.
CLI Skills - drop-in agent skills for Claude Code / Cursor / Codex that teach your assistant how to use the CLI.
n0an/vivadicta-mcp - the Homebrew shim source.