wispr-flow-write-mcp

An MCP server that lets an AI agent change what you can change in the Wispr Flow app: your personal dictionary, snippets, writing styles and polish instructions, custom transforms, scratchpad notes, todos, meeting titles and notes, and your profile name.

It is the write companion to Wispr Flow's official MCP server, which is read-only.

Unofficial. Not affiliated with or endorsed by Wispr.

Why

Wispr Flow's official MCP server covers the Notetaker: meetings, calendar events, and scratchpad notes. It can read them but not change them, and it doesn't expose the dictionary, snippets, styles, or transforms at all. There is no public API for any of these. So an agent that notices Flow keeps mishearing a name, or that you want a snippet for your sign-off, has no way to act on it.

This server fills that gap. Every tool talks to the same endpoint the Wispr Flow desktop app uses for its own sync, so changes show up in the app on its next sync.

Run both side by side: the official server to find things, this one to change them.

Related MCP server: @restforge-dev/mcp-server

Tools

update_preferences accepts:

• personalizationOnboardingCompleted: explicit true/false. The app uses configured styles only after this is true; the server never enables it implicitly.

• personalization_styles: personal (messages), work (Slack, Teams), email, other, each one of formal, casual, veryCasual, excited, default.

• polish_instructions: { default: { label: on/off }, custom: { "your instruction": on/off } }. Set a custom instruction to null to delete it.

• output_languages (codes such as ["en", "es"]), auto_cleanup_level (none, light, medium, high, full).

• privacy_mode and share_data are inverse views of one training-data choice. Setting either automatically sets the other to its opposite; contradictory input is rejected before any request. Neither turns transcription into offline processing.

• cloud_sync, teammates_added_digest_enabled.

• notetaker_transcript_retention and notetaker_preference (default note visibility, calendar notice, auto-share).

Dictation cloud storage, model improvement, local history, and Notetaker retention are separate controls. Privacy Mode is not a blanket no-storage switch. Organization and BAA settings can enforce stricter choices; this server cannot override those.

Turning cloud_sync off also stops this server's changes from reaching the app. The data-retention policy (local_data_policy) is not exposed, because changing it makes the app delete local history.

Requirements

• macOS with the Wispr Flow desktop app installed and signed in

• Node.js 18 or later

Install

git clone https://github.com/abhaymettu/wispr-flow-write-mcp.git
cd wispr-flow-write-mcp
npm install

Claude Code:

claude mcp add --scope user wispr-flow-write -- node /absolute/path/to/wispr-flow-write-mcp/index.js

Claude Desktop, Cursor, or any other MCP client (JSON config):

{
  "mcpServers": {
    "wispr-flow-write": {
      "command": "node",
      "args": ["/absolute/path/to/wispr-flow-write-mcp/index.js"]
    }
  }
}

Install as a Claude plugin

This repo is also packaged as a Claude plugin (MCP server + setup skill).

When the plugin is approved and listed in the Claude plugin directory, install it from the community marketplace in Claude Code:

/plugin marketplace add anthropics/claude-plugins-community
claude plugin install wispr-flow-write@claude-community

The plugin ships disabled by default (defaultEnabled: false) because it connects to an external service; enable it with claude plugin enable wispr-flow-write or from /plugin. Dependencies install automatically on first start.

To test the plugin layout locally from a clone:

claude plugin validate . --strict
claude --plugin-dir .

Usage

Ask your agent in plain language. For example:

• "Flow keeps writing 'whisper flow'. Add Wispr Flow to my dictionary."

• "Here are 200 names from my contacts. Dry-run a bulk add first, then add the ones that aren't there yet."

• "Is Kubernetes in my Flow dictionary?"

• "Add a snippet: when I say 'my calendar link', type https://cal.com/me."

• "Switch my email style to formal."

Words are single-line, up to 255 characters. Matching ignores case, so github is reported as already present when you have GitHub. To change a word's casing, remove it and add it again.

Errors and retries

Errors say what to do next: an expired or rejected session asks you to open the Wispr Flow app, and an API error shows the status and the server's message.

Each request is retried once when a retry can help: a network failure, a 502, 503 or 504, or a 401 sent with a token the app has since replaced. Every write is keyed by item id or replaces a whole record, so a retried write that already landed changes nothing. Requests time out after 30 seconds. A 409 on update_preferences (the preferences changed after they were read) is reported, not retried.

Seeing changes in the app

• Dictionary and snippets: the app syncs these when it starts, after an edit in the app, and when you press Refresh on the Dictionary page. It does not poll. Press Refresh or restart Flow.

• Notes, todos, meetings, preferences: the app pulls these on its own sync cycle, so they show up without doing anything.

• Transforms: the app loads them when it starts. Restart Flow to see a change.

Reverse-engineering review

The October 8 review used REA static analysis and the installed Wispr Flow 1.6.1102 bundle. See findings and changes for scope, evidence, limits, and tests. No vendor code is included. Native integrity and live service behavior were not validated.

Where the token comes from

Nothing is hardcoded and nothing is stored by this server.

The Wispr Flow desktop app signs in with Supabase and keeps its session as plaintext JSON at:

~/Library/Application Support/Wispr Flow/session.json

under a key shaped like sb-<project>-auth-token. On every tool call the server reads that file, takes the access_token, checks expires_at, and sends the token as the Authorization header (the raw token, with no Bearer prefix, which is what the app sends).

The server never refreshes the token. Supabase rotates refresh tokens, so refreshing from outside the app could sign the app out. If the token has expired, the tool returns an error asking you to open Wispr Flow; the app refreshes its own session and the next call works.

Any process running as your user can read that file. This server doesn't change that exposure, but you should know it exists.

How it works

Found by reading the app's bundled JavaScript (Wispr Flow 1.6.957 for macOS). All of it goes to https://api.wisprflow.ai/api/v1:

Deletes are soft (is_deleted: true with a newer modified_at), which is how the app deletes and what its sync propagates. The server never writes to the app's SQLite database, which avoids fighting the running app over its own file.

Meeting edits resend the fields the app itself pushes, copied from the server's copy, so only the title or notes change. Transcripts, sharing, and deleting meetings stay in the app.

Because this relies on undocumented endpoints, a Wispr Flow update can break it. If that happens, open an issue with your app version.

Development

npm test

The tests start the server over stdio and point it at a fake dictionary API on localhost (through the WISPR_FLOW_API and WISPR_FLOW_SESSION environment variables), so they run offline and never touch your account. For changes to how the server talks to the real API, also follow the live testing steps in AGENTS.md.

License

MIT