Voice Coding in AI IDEs

HyperWhisper works with AI coding agents through the local MCP bridge and the Code preset. These two features put your transcript in the correct format before an agent reads it. Cursor and Claude Code are two such agents. This page describes the full workflow. Each section links to the reference page for that feature.

Prerequisites

You installed HyperWhisper and opened it one time.
Settings → Local API is on. This setting writes the discovery file that the MCP bridge reads.
Node.js 18 or a later version is on your PATH. The command node --version prints the version number. Node includes the npx command.

The MCP bridge works on macOS and Windows. Both apps write the discovery file that the bridge reads. iOS does not support editor integrations.

The Linux app writes a discovery file too, but the bridge does not read the Linux path yet. Linux users can call the local API directly. See MCP Setup.

Agent integration via MCP

The @hyperwhisper/mcp package is a Model Context Protocol bridge for the local API. Configure the bridge one time. Then an MCP-capable agent can call HyperWhisper as a tool. Cursor, Claude Desktop, Claude Code, Zed, and custom code are such agents.

Tools the agent gets

Tool	What it does
`health`	Shows that HyperWhisper runs.
`list_models`	Returns the catalog of the available voice and post-processing models.
`list_modes`	Lists your saved transcription Modes.
`transcribe`	Transcribes the audio file at an absolute path.
`post_process`	Rewrites text with a preset (`hyper`, `note`, `email`, `commit`, `prompt`), or with your own instruction in the separate `prompt` field. Only `hyper` and `note` map to a real backend preset. The app does not recognize `email`, `commit`, or the `prompt` preset value, and it gives Hyper-style output for all three.
`search_recordings`	Searches past transcripts for a substring.
`get_recording`	Returns one transcript row by ID.

Setup

Cursor
Claude Desktop
Claude Code

Edit ~/.cursor/mcp.json and add the hyperwhisper entry:

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

Restart Cursor. The server appears under Settings → MCP.

Edit the configuration file. Use ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows:

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

Quit Claude Desktop, then open it again. The hammer icon in the composer lists hyperwhisper.

Run the CLI helper one time:

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

In a new session, /mcp lists hyperwhisper with its tools.

Test the bridge

Open a new agent session. Then give this prompt:

Ask hyperwhisper to run a health check.

The agent calls the health tool and reports the app version. If you have an audio file, give this prompt:

Use hyperwhisper to transcribe /Users/me/Desktop/test.wav

The agent calls transcribe and returns the text in the reply. For all tool signatures and more troubleshooting, see MCP Setup.

Code preset for voice-to-code

If you dictate code and not prose, use a mode with the Code preset. The preset converts spoken symbol names into code syntax. Also turn off Capitalization and Punctuation in that mode. Then your identifiers stay exactly as you speak them. The preset does not change these two options for you.

You say	You get
`open paren`	`(`
`close paren`	`)`
`fat arrow`	`=>`
`camel case user name`	`userName`

Set up a Code mode

Create a new mode

Click + in the mode list. To change a mode that exists, open that mode instead.

Choose the Code preset

Select Code in the preset picker. This preset sets the post-processing instructions for symbol conversion.

Enable AI post-processing

Set AI Post-Processing to Cloud or Local. The Code preset needs a post-processing pass to convert spoken symbols.

Turn off auto-capitalization and punctuation

In the formatting options of the mode, make sure that Capitalization and Punctuation are off. The Code preset needs raw output that keeps your letter case.

Turn on Screen Text for your Code mode. Then the AI can read your current file and spell identifiers, class names, and variable names correctly.

Developer Mode for file context

Developer Mode is not available in the shipping app. This feature tagged files by voice with @ mentions, for example “at app.swift, add error handling”. This section documented that feature before. It stays here as a placeholder until we make a product decision about the return of the feature.

Auto-paste into your editor

Turn on auto-paste. Then HyperWhisper puts the finished transcript into your focused editor window. You do not paste it manually.

Enable auto-paste

Open Settings → Text Output. Then turn on Paste result automatically.

Grant Accessibility permission

macOS asks for this permission the first time. If you did not give it, open System Settings → Privacy & Security → Accessibility. Then turn on HyperWhisper.

After a recording stops, HyperWhisper copies the transcript to the clipboard. Then it focuses your editor and sends a standard paste command. HyperWhisper then puts the previous clipboard contents back. For all configuration options, see Auto Paste & Clipboard Behavior. These options include the clipboard restore delay.

Workflows

Cursor agent: dictate a prompt

Switch to your Code mode.
Press your record shortcut. Then speak your prompt, for example “refactor the onClick handler in components/button to use useCallback”.
HyperWhisper transcribes your speech and pastes the result into the Cursor composer.
The Cursor agent reads the prompt and generates code.

Standalone transcription via MCP

An agent session can call transcribe directly on a recorded file:

Use hyperwhisper to transcribe /Users/me/recordings/meeting.m4a and post_process the result with the "note" preset.

The agent calls the two tools in sequence. Then it returns the formatted transcript in the reply.

Troubleshooting

The MCP server does not appear in the IDE

Make sure that node --version prints 18 or a higher number.
Turn Settings → Local API off, then on again. Then restart the IDE.
On the first run, npx -y downloads the package. This download can take some seconds on a slow connection.

HYPERWHISPER_NOT_RUNNING error Open HyperWhisper. Turn on Settings → Local API. Then run the agent prompt again. The bridge reads the discovery file for each request. The Code preset does not convert symbols Make sure that AI Post-Processing is set to Cloud or Local for the mode. The Code preset has no effect when post-processing is off. Auto-paste does not work

Give Accessibility permission in System Settings → Privacy & Security → Accessibility.
Make sure that the IDE window is focused when the recording stops.
Paste into Notes or TextEdit. This test shows if the error is specific to your editor.

Limitations

The MCP bridge needs HyperWhisper to run. There is no background listener that starts on its own.
Local transcription with local post-processing adds latency. For long code blocks, cloud transcription is faster.
The Code preset controls the formatting instructions for the AI. Cloud post-processing models can still rephrase the output more than the preset intends.
iOS does not support MCP integration.

Getting Started

Plans & Billing

Transcription & Models

The Interface

Features

Settings

Privacy & Security

Developer & API

Troubleshooting

Windows

Voice Coding in AI IDEs

Prerequisites

Agent integration via MCP

Tools the agent gets

Setup

Test the bridge

Code preset for voice-to-code

Set up a Code mode

Developer Mode for file context

Auto-paste into your editor

Workflows

Cursor agent: dictate a prompt

Standalone transcription via MCP

Troubleshooting

Limitations

​Prerequisites

​Agent integration via MCP

​Tools the agent gets

​Setup

​Test the bridge

​Code preset for voice-to-code

​Set up a Code mode

​Developer Mode for file context

​Auto-paste into your editor

​Workflows

​Cursor agent: dictate a prompt

​Standalone transcription via MCP

​Troubleshooting

​Limitations

Prerequisites

Agent integration via MCP

Tools the agent gets

Setup

Test the bridge

Code preset for voice-to-code

Set up a Code mode

Developer Mode for file context

Auto-paste into your editor

Workflows

Cursor agent: dictate a prompt

Standalone transcription via MCP

Troubleshooting

Limitations