OpenWhispr MCP Server

Remote MCP server for accessing your OpenWhispr notes, folders, transcriptions, dictionary, snippets, and usage stats from any AI assistant that supports the Model Context Protocol.

Hosted at https://mcp.openwhispr.com/mcp

Setup

1. Get an API key

Skip this step if you are connecting from Claude (web, desktop, or mobile): it signs you in with OAuth and never needs an API key.

For other clients, generate an API key from the OpenWhispr desktop app under Settings > API Keys. Your key starts with owk_live_.

Alternative: Agent self-setup

AI assistants can create their own API key without the desktop app:

1. Request a code: POST https://api.openwhispr.com/api/v1/auth/email-code with {"email": "[email protected]"}
2. Enter the code: Check your email for a 6-digit verification code
3. Verify: POST https://api.openwhispr.com/api/v1/auth/email-code/verify with {"email": "...", "code": "123456"}
4. Create a key: POST https://api.openwhispr.com/api/v1/keys/create with Authorization: Bearer owt_... and {"name": "My Agent", "scopes": ["notes:read", "notes:write", "dictionary:write", "snippets:write"]}

The returned owk_live_ key works the same as one created in the desktop app.

2. Connect your AI assistant

Claude (web, desktop, mobile)

1. Open Customize > Connectors > Add custom connector
2. Paste https://mcp.openwhispr.com/mcp and click Add
3. Sign in to OpenWhispr and approve the requested access

No API key is needed. Claude receives a short-lived, scoped token that it refreshes automatically.

Claude Code

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

Cursor / VS Code

Add to your MCP config (~/.cursor/mcp.json or VS Code MCP settings):

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

Available Tools

Beta: transcribe_audio accepts clips up to 3 MB (wav, mp3, m4a, ogg, flac, or webm), requires a Pro or Business plan, and is limited to 600 minutes per month. Limits and response shape may change during the beta. For longer files use the OpenWhispr CLI, which can also transcribe locally for free.

Required Scopes

OAuth clients ask for scopes when they connect (Claude asks for all of them, and the consent screen shows what was requested). When using an API key, create it with only the scopes you need:

Example Prompts

• “Show me my recent notes”
• “Search my notes for 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”
• “Add ‘Orukeet’ and ‘Parakeet’ to my dictionary”
• “Remove duplicate or misspelled words from my dictionary”
• “Create a snippet so saying ‘my address’ inserts my mailing address”
• “Transcribe this voice memo”

Disconnecting

In Claude, open the connector and choose Disconnect. OAuth access tokens expire after 1 hour and are refreshed automatically while the connector is in use; a connector that goes unused for 30 days stops working on its own. API keys are revoked from Settings > API Keys in the desktop app.

Development

OpenAI directory domain verification

Set OPENAI_APPS_CHALLENGE to the exact token supplied by the OpenAI plugin submission portal, in the deployment serving mcp.openwhispr.com. After an authorized deployment, GET /.well-known/openai-apps-challenge returns only that token as plain text, without caching or a trailing newline. The endpoint returns 404 while the variable is unset. Do not commit the token or put it in the plugin ZIP. If the host already serves a challenge for another plugin, use the portal’s allowed parent-domain option instead of replacing its token.

This route does not grant account access or change the MCP OAuth flow.

Local checks

npm install
npm run build
npm test

Set OPENWHISPR_API_URL to override the API base URL for local development. MCP_RESOURCE_URL and OPENWHISPR_AUTH_URL override the public MCP URL and the OAuth issuer advertised to clients (defaults: https://mcp.openwhispr.com/mcp, https://auth.openwhispr.com).