> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openwhispr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect your AI assistant to OpenWhispr using the Model Context Protocol.

The OpenWhispr MCP server lets AI assistants like Claude, Cursor, and VS Code access your notes, folders, transcriptions, and usage stats directly.

It's hosted at `https://mcp.openwhispr.com/mcp` and uses the Streamable HTTP transport — no local install needed.

## Setup

You'll need an [API key](/integrations/api-keys) with the scopes you want the assistant to access.

<Tip>
  AI assistants can create their own API key automatically — see [Agent setup](/integrations/agent-setup).
</Tip>

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add openwhispr --transport http https://mcp.openwhispr.com/mcp \
      --header "Authorization: Bearer owk_live_YOUR_KEY"
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Go to **Settings > Integrations > Add MCP Server** and enter:

    * **URL:** `https://mcp.openwhispr.com/mcp`
    * **Authorization:** `Bearer owk_live_YOUR_KEY`
  </Tab>

  <Tab title="Cursor / VS Code">
    Add to your MCP config file (`~/.cursor/mcp.json` or VS Code MCP settings):

    ```json theme={null}
    {
      "mcpServers": {
        "openwhispr": {
          "url": "https://mcp.openwhispr.com/mcp",
          "headers": {
            "Authorization": "Bearer owk_live_YOUR_KEY"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 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                                   |

## Required scopes

Create the API key with 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`                                                                     |

## 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"

## How it works

The MCP server is a thin wrapper around the [OpenWhispr API](/api/overview). Your API key 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.