MCP server

vowen mcp runs a Model Context Protocol server over stdio. Point any MCP client at it and that client can search your dictations, read your meeting notes, transcribe audio files, and manage your dictionary, all through the running Vowen app.

claude mcp add vowen -- vowen mcp

That is the whole setup for Claude Code. Restart your session and ask it something like “what did I dictate about the migration last week?”

This is the outbound direction: agents reading Vowen.Vowen also has an inbound MCP feature, Connectors, where Vowen’s own AI reaches out into your other apps. The two run in opposite directions:

vowen mcp (this page): Vowen is the server. An external agent connects to it and reads your Vowen data. Runs through the CLI, no plan gate beyond what the underlying operations already require.
Connectors: Vowen is the client. It connects out to Linear, Notion, GitHub and others so its AI can look things up while answering you. Configured in the app, Pro and experimental.

Requirements

The vowen CLI installed and on your PATH.
The Vowen desktop app installed. The MCP server launches it in the background on the first tool call if it is not already running.

The server holds one connection to the app for the whole session and re-establishes it automatically if the app restarts, so a Vowen update mid-conversation does not break your agent.

Setting up a client

Claude Code
Opencode and other clients

claude mcp add vowen -- vowen mcp

Verify with claude mcp list, then start a session and ask it to search your history.

Any client that speaks MCP over stdio works. Register a local server with:

command: vowen
arguments: ["mcp"]

That is all the process needs. There are no environment variables to set and no port to configure, because the CLI discovers the running app itself.If your client wants an absolute path rather than a bare command, vowen doctor prints the path the binary was installed to.

Do not run vowen mcp in your terminal to “check that it works”. It reads JSON-RPC from stdin and will simply sit there. Use vowen doctor to verify the connection and let the client own the process.

Available tools

23 tools, grouped by what they touch.

Reading your data

Tool	What it does	Key parameters
`search`	Full-text search across dictations, file transcriptions, and meeting notes. Returns compact matches	`query` (required), `limit`, `type`
`history`	List recent items, newest first	`limit`, `type`, `since`, `before`
`read_item`	Full text and metadata of one item. Omit the id for the latest dictation	`id`
`stats`	Lifetime dictation statistics, last-30-days activity, and per-type counts	none

type is one of dictation, transcription, note, or all. search defaults to all, history defaults to dictation. Dates are YYYY-MM-DD. Item ids may be given as a prefix. Search first, then read_item on whatever looked relevant. search deliberately returns snippets rather than whole transcripts.

Meeting notes

Tool	What it does	Key parameters
`note_create`	Create a meeting note from text, Markdown accepted	`text` (required), `title`, `contextNotes`
`note_update`	Update a note’s title, text, context notes, or summary	`id` (required), `title`, `text`, `contextNotes`, `summary`

Transcription

Tool	What it does	Key parameters
`transcribe_file`	Queue an audio or video file for transcription. Returns a job id	`path` (required, absolute), `modelId`, `language`, `diarize`
`transcription_status`	Job status: `processing`, `done`, or `error`, plus the transcript once done	`id` (required)

Transcription is asynchronous. transcribe_file returns immediately, so poll transcription_status until it reports done. Anything you leave out falls back to the user’s configured model and language.

Tool	What it does	Key parameters
`tags_list`	List tags. Omit the pool to get both	`pool` (`notes` or `transcriptions`)
`tag_item`	Add or remove tags on a note or transcription	`id` (required), `add`, `remove`

Dictionary and text rules

Tool	What it does	Key parameters
`vocab_list`	List custom vocabulary terms	none
`vocab_add`	Add a vocabulary term. The term keeps the case you give it, and adding one that already exists is a no-op	`word` (required)
`vocab_remove`	Remove a vocabulary term, matching the whole term and ignoring case	`word` (required)
`replacements_list`	List text replacements applied to transcripts	none
`replacements_set`	Create or update a replacement, keyed by trigger	`trigger`, `replacement` (both required)
`replacements_remove`	Remove a replacement by trigger	`trigger` (required)
`expansions_list`	List live typing expansions	none
`expansions_set`	Create or update an expansion, keyed by shortcut	`shortcut`, `body` (both required)

Settings and app control

Tool	What it does	Key parameters
`settings_get`	Read settings, secrets redacted. Optionally one top-level key	`key`
`settings_set`	Set a whitelisted setting	`key`, `value` (both required)
`record_start`	Start dictation recording in the app	none
`record_stop`	Stop recording, which transcribes what was captured	none
`app_status`	App version, plan, active model, recording state	none

settings_set writes only the same whitelisted keys the CLI allows. Shortcuts, API keys, sync, and account settings cannot be changed by an agent. The full list is on the command reference.

What an agent can and cannot reach

It reads and writes real data. These tools are not a sandbox. note_update, vocab_add, replacements_set and settings_set change what is in your app.
It cannot delete anything. No delete tool is exposed. vowen delete exists on the CLI, but there is no MCP equivalent.
Secrets never leave. settings_get redacts every key that looks like an API key, token, secret, password, or licence.
Everything goes through the app. The server has no direct access to your files or stores. It makes the same loopback API calls the CLI does, so plan limits and validation apply identically.
Nothing is exposed off-machine. The transport is stdio between your client and the vowen process, and the app’s API binds 127.0.0.1 only.

Troubleshooting

The client shows the server as failed or disconnected

Confirm the binary is reachable under the same PATH your client sees:

which vowen        # macOS
where vowen        # Windows
vowen doctor

GUI-launched clients frequently do not inherit the PATH from your shell profile. If vowen works in your terminal but not from the client, register it by absolute path instead. vowen doctor prints the location.

Every tool call returns an error about the app

Every tool call goes through the desktop app, so it has to be reachable. Run vowen doctor. If it reports “App: not reachable”, start Vowen and try again. See the CLI troubleshooting section for the rest.

Tools return 'upgrade_required'

A few operations are plan-gated. Exceeding the free lifetime transcription limit, or queuing a second transcription while one is already running, both surface as an error in the tool result. Check app_status for the current plan.

Updating the CLI while an agent is connected

vowen update handles this. On Windows the running executable is renamed out of the way rather than overwritten, so an active vowen mcp process does not block the update. The client will pick up the new binary the next time it spawns the server.

CLI overview

How the CLI talks to the app

Connectors

The other direction: Vowen’s AI reading your other apps

Vowen CLI

Requirements

Setting up a client

Available tools

Reading your data

Meeting notes

Transcription

Tags

Dictionary and text rules

Settings and app control

What an agent can and cannot reach

Troubleshooting

CLI overview

Connectors

​Requirements

​Setting up a client

​Available tools

​Reading your data

​Meeting notes

​Transcription

​Tags

​Dictionary and text rules

​Settings and app control

​What an agent can and cannot reach

​Troubleshooting

​Related

CLI overview

Connectors

Requirements

Setting up a client

Available tools

Reading your data

Meeting notes

Transcription

Tags

Dictionary and text rules

Settings and app control

What an agent can and cannot reach

Troubleshooting

Related