# @hyperwhisper/mcp

Model Context Protocol server that lets Cursor, Claude Desktop, Claude Code, and any other MCP-capable agent talk to a running [HyperWhisper](https://hyperwhisper.com) app. The agent gets seven tools: `health`, `list_models`, `list_modes`, `transcribe`, `post_process`, `search_recordings`, and `get_recording`.

`transcribe` can also write the transcript straight to a file: set `output_path` and the tool saves the text to disk and returns only a short confirmation (path, character count, 200-char preview) instead of the full transcript — much more context-efficient for long recordings or when the agent only needs the text on disk. `if_exists` controls collisions (`fail` / `overwrite` / `append`), and `post_process_preset` / `post_process_prompt` clean the text up before it's written.

## Prerequisites

1. Install HyperWhisper for macOS or Windows.
2. Open **Settings → Local API** and turn the toggle on.
3. Make sure `node` (>= 18) is on your `PATH` so `npx` can run the bridge.

The MCP server discovers the local API automatically by reading the discovery file the HyperWhisper app writes when the toggle is on:

- macOS: `~/Library/Application Support/HyperWhisper/local-api.json`
- Windows: `%LOCALAPPDATA%\HyperWhisper\local-api.json`

## Install

The bridge is published as `@hyperwhisper/mcp`. No global install needed:

```bash
npx -y @hyperwhisper/mcp
```

## Client configuration

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "hyperwhisper": {
      "command": "npx",
      "args": ["-y", "@hyperwhisper/mcp"]
    }
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "hyperwhisper": {
      "command": "npx",
      "args": ["-y", "@hyperwhisper/mcp"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add hyperwhisper -- npx -y @hyperwhisper/mcp
```

## Verify

In a fresh agent session ask:

> Use hyperwhisper to transcribe `/Users/me/voice.wav`.

The agent should call the `transcribe` tool and return the text.

## Docs

Full setup guide and troubleshooting: <https://hyperwhisper.com/docs/api-reference/local-api/mcp-setup>.

## License

MIT