MCP server

The OpenWhispr MCP server lets AI assistants like Claude, Cursor, and VS Code access your notes, folders, transcriptions, dictionary, snippets, and usage stats directly — and, in beta, transcribe audio. It’s hosted at https://mcp.openwhispr.com/mcp and uses the Streamable HTTP transport — no local install needed.

Setup

Claude’s Connectors flow signs you in to OpenWhispr with OAuth, so it needs no API key. Clients that send headers instead — Claude Code, Cursor, and VS Code — need a personal API key (owk_live_) with the scopes you want the assistant to access. The MCP server reaches your own notes, so workspace keys aren’t supported here.

AI assistants can create their own API key automatically — see Agent setup.

Claude
Claude Code
Cursor
VS Code

In Claude on the web, in the desktop app, or on mobile, go to Customize > Connectors > Add custom connector, paste https://mcp.openwhispr.com/mcp, and click Add. Claude sends you to OpenWhispr to sign in and approve the permissions it asked for — no API key needed.

claude mcp add openwhispr --transport http https://mcp.openwhispr.com/mcp \
  --header "Authorization: Bearer owk_live_YOUR_KEY"

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "openwhispr": {
      "url": "https://mcp.openwhispr.com/mcp",
      "headers": {
        "Authorization": "Bearer owk_live_YOUR_KEY"
      }
    }
  }
}

Add to .vscode/mcp.json in your workspace, or run MCP: Open User Configuration from the Command Palette for a config that follows you across projects:

{
  "servers": {
    "openwhispr": {
      "type": "http",
      "url": "https://mcp.openwhispr.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:openwhispr_api_key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "openwhispr_api_key",
      "description": "OpenWhispr API key",
      "password": true
    }
  ]
}

VS Code prompts for the key once and stores it securely instead of writing it into the config file. See the VS Code MCP server reference for the full schema.

Permissions and disconnecting

When you connect through Claude’s Connectors flow, the consent screen describes each permission Claude asked for in plain language; the scopes table below maps those permissions to scopes and tools. The token Claude receives expires after 1 hour and is refreshed automatically while the connector is in use, so it stays connected until you disconnect it or leave it unused for 30 days. To remove access, use Disconnect on the OpenWhispr connector in Claude.

Available tools

Once connected, your assistant has access to these tools:

Tool	Description
`list_notes`	List notes with optional folder filtering and pagination
`get_note`	Get a single note by ID
`create_note`	Create a new note
`update_note`	Update a note’s title, content, or folder
`delete_note`	Delete a note
`search_notes`	Semantic and full-text search across notes
`list_folders`	List all folders
`create_folder`	Create a new folder
`list_transcriptions`	List transcription history with filtering by language or note
`get_transcription`	Get a transcription by ID, including speaker-attributed segments with timestamps
`get_note_transcript`	Get the transcript for a specific note with structured segments
`get_usage`	Get usage stats, word counts, and plan details
`list_dictionary`	List your custom dictionary words
`add_dictionary_words`	Add one or more words to your dictionary
`update_dictionary_word`	Change a dictionary word’s spelling
`delete_dictionary_word`	Remove a word from your dictionary
`list_snippets`	List your snippets
`create_snippet`	Create a snippet — a trigger phrase and the text it expands into
`update_snippet`	Change a snippet’s trigger or replacement
`delete_snippet`	Delete a snippet
`transcribe_audio`	Transcribe an audio clip with OpenWhispr Cloud (beta)

Transcribing audio

transcribe_audio takes audio_base64 and mime_type, plus optional language and prompt (names and jargon to spell correctly). The decoded audio is capped at 3 MB, and the same rules apply as for the REST endpoint: a Pro or Business plan, the transcriptions:write scope, 600 audio minutes per calendar month, and one transcription at a time per key or connection.

Cloud transcription through the API is in beta. Limits, response shape, and availability may change, and there is no SLA. For long recordings or free, private transcription, use the OpenWhispr CLI with the desktop app running.

Required scopes

Claude’s Connectors flow asks for all of these on the consent screen. When you create an API key instead, grant only the scopes you need.

Scope	Tools
`notes:read`	`list_notes`, `get_note`, `search_notes`, `list_folders`, `get_note_transcript`
`notes:write`	`create_note`, `update_note`, `delete_note`, `create_folder`
`transcriptions:read`	`list_transcriptions`, `get_transcription`
`usage:read`	`get_usage`
`transcriptions:write`	`transcribe_audio`
`dictionary:read`	`list_dictionary`
`dictionary:write`	`add_dictionary_words`, `update_dictionary_word`, `delete_dictionary_word`
`snippets:read`	`list_snippets`
`snippets:write`	`create_snippet`, `update_snippet`, `delete_snippet`

Example prompts

Try these after connecting:

“Show me my recent notes”
“Search my notes for the meeting with the design team”
“Create a note titled ‘Project Ideas’ in my Work folder”
“How many words have I used this month?”
“List my transcriptions from today”
“Get the transcript from my last meeting note as subtitles”
“Show the transcript for note [id] with speaker segments”
“Add Siobhán, Kubernetes and SOC 2 to my dictionary”
“Make a snippet so ‘cal link’ becomes my booking URL”
“Transcribe this voice memo”

How it works

The MCP server is a thin wrapper around the OpenWhispr API. Your API key or OAuth token is passed through on every request — the MCP server doesn’t store credentials or session state. Each request creates a fresh, stateless connection. This means it scales horizontally and works with any MCP client that supports Streamable HTTP transport.

Overview

CLI

Integrations

Open source

Setup

Permissions and disconnecting

Available tools

Transcribing audio

Required scopes

Example prompts

How it works

​Setup

​Permissions and disconnecting

​Available tools

​Transcribing audio

​Required scopes

​Example prompts

​How it works

Setup

Permissions and disconnecting

Available tools

Transcribing audio

Required scopes

Example prompts

How it works