Skip to content
Back to search

mcp-voice-hooks

MCP server plugin for voice input and output in Claude Code

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/johnmatthewtennant--mcp-voice-hooks/badge.svg)](/listings/johnmatthewtennant--mcp-voice-hooks)

HTML

<a href="/listings/johnmatthewtennant--mcp-voice-hooks"><img src="/api/listings/johnmatthewtennant--mcp-voice-hooks/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installation is easy.

1. Install Claude Code

npm install -g @anthropic-ai/claude-code

2. Install Voice Mode

Add the following to any Claude Code settings file (`~/.claude/settings.json`, `.claude/settings.json`, or `.claude/settings.local.json`):

{
  "extraKnownMarketplaces": {
    "mcp-voice-hooks-marketplace": {
      "source": {
        "source": "git",
        "url": "https://github.com/johnmatthewtennant/mcp-voice-hooks.git"
      }
    }
  },
  "enabledPlugins": {
    "mcp-voice-hooks-plugin@mcp-voice-hooks-marketplace": true
  }
}

Restart Claude Code. Set `"mcp-voice-hooks-plugin@mcp-voice-hooks-marketplace"` to `false` to temporarily disable.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 13 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "mcp-voice-hooks-marketplace",
  3. "owner": {
  4. "name": "John Matthew Tennant"
  5. },
  6. "plugins": [
  7. {
  8. "name": "mcp-voice-hooks-plugin",
  9. "source": "./plugin",
  10. "description": "Real-time voice interaction for Claude Code. Speak naturally while Claude works - interrupt, redirect, or provide continuous feedback without stopping."
  11. }
  12. ]
  13. }
README.md · README · 210 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Voice Mode for Claude Code
  2. Voice Mode for Claude Code allows you to have a continuous two-way conversation with Claude Code, hands-free.
  3. It uses the new [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) to deliver voice input to Claude while it works.
  4. This lets you speak continuously to Claude - interrupt, redirect, or provide feedback without stopping what Claude is doing.
  5. Optionally enable text-to-speech to have Claude speak back to you.
  6. Voice recognition and text-to-speech are handled by the browser, so there is nothing to download, and no API keys are needed.
  7. ## Demo Video
  8. [![Demo Video](https://img.youtube.com/vi/GbDatJtm8_k/0.jpg)](https://youtu.be/GbDatJtm8_k)
  9. ## Requirements
  10. - Claude Code 2.1.69 or later (run `claude --version` to check)
  11. - macOS (for system text-to-speech)
  12. - Chrome or Safari (for speech recognition)
  13. ## Installation
  14. Installation is easy.
  15. ### 1. Install Claude Code
  16. ```bash
  17. npm install -g @anthropic-ai/claude-code
  18. ```
  19. ### 2. Install Voice Mode
  20. Add the following to any Claude Code settings file (`~/.claude/settings.json`, `.claude/settings.json`, or `.claude/settings.local.json`):
  21. ```json
  22. {
  23. "extraKnownMarketplaces": {
  24. "mcp-voice-hooks-marketplace": {
  25. "source": {
  26. "source": "git",
  27. "url": "https://github.com/johnmatthewtennant/mcp-voice-hooks.git"
  28. }
  29. }
  30. },
  31. "enabledPlugins": {
  32. "mcp-voice-hooks-plugin@mcp-voice-hooks-marketplace": true
  33. }
  34. }
  35. ```
  36. Restart Claude Code. Set `"mcp-voice-hooks-plugin@mcp-voice-hooks-marketplace"` to `false` to temporarily disable.
  37. ## Usage
  38. ### 1. Start Claude Code
  39. ```bash
  40. claude
  41. ```
  42. ### 2. Start Listening
  43. The browser interface will automatically open after 3 seconds (<http://localhost:5111>).
  44. Click "Start Listening"
  45. ### 3. Speak
  46. Say something to Claude. You will need to send one message in the Claude Code CLI to start the conversation.
  47. ### 4. Trigger Word Mode (Optional)
  48. By default, utterances are sent automatically when you pause. You can switch to "Wait for Trigger Word" mode in the browser interface:
  49. 1. Toggle to "Wait for Trigger Word" mode
  50. 2. Enter a trigger word (e.g., "send", "claude", "go")
  51. 3. Speak your message(s) - they will queue up in the browser
  52. 4. Say your trigger word to send all queued messages at once (or click "Send Now")
  53. The trigger word is case-insensitive and will be automatically removed from your message before sending.
  54. ## Browser Compatibility
  55. - ✅ **Chrome**: Full support for speech recognition, browser text-to-speech, and system text-to-speech
  56. - ⚠️ **Safari**: Full support for speech recognition and system text-to-speech, but browser text-to-speech cannot load high-quality voices
  57. - ❌ **Edge**: Speech recognition not working on Apple Silicon (language-not-supported error)
  58. ## Voice responses
  59. There are two options for voice responses:
  60. 1. Browser Text-to-Speech
  61. 2. System Text-to-Speech
  62. ### Selecting and downloading high quality System Voices (Mac only)
  63. Mac has built-in text to speech, but high quality voices are not available by default.
  64. You can download high quality voices from the system voice menu: `System Settings > Accessibility > Spoken Content > System Voice`
  65. Click the info icon next to the system voice dropdown. Search for "Siri" to find the highest quality voices. You'll have to trigger a download of the voice.
  66. Once it's downloaded, you can select it in the Browser Voice (Local) menu in Chrome.
  67. Test it with the bash command:
  68. ```bash
  69. say "Hi, this is your Mac system voice"
  70. ```
  71. To use Siri voices with voice-hooks, you need to set your system voice and select "Mac System Voice" in the voice-hooks browser interface.
  72. Other downloaded voices will show up in the voice dropdown in the voice-hooks browser interface so you can select them there directly, instead of using the "Mac System Voice" option.
  73. There is a bug in Safari that prevents browser text-to-speech from loading high-quality voices after browser restart. This is a Safari Web Speech API limitation. To use high-quality voices in Safari you need to set your system voice to Siri and select "Mac System Voice" in the voice-hooks browser interface.
  74. ## Known Limitations
  75. - **Background agents don't notify in voice mode.** When Claude launches background agents (via the Agent tool), their completion notifications appear in the conversation text but don't trigger hooks. This means you won't hear a voice notification when a background task finishes. **Workaround:** Manually check background agent status, or avoid using background agents during voice sessions. *(Verified with Claude Code 2.1.69, March 2026)*
  76. ## Uninstallation
  77. Remove the `extraKnownMarketplaces` and `enabledPlugins` entries from your settings file and restart Claude Code.
  78. ### Alternative: Manual Installation
  79. If you prefer not to use the plugin system, you can install manually:
  80. ```bash
  81. npx mcp-voice-hooks@latest install-hooks
  82. claude mcp add voice-hooks npx mcp-voice-hooks@latest
  83. ```
  84. To uninstall:
  85. ```bash
  86. claude mcp remove voice-hooks
  87. npx mcp-voice-hooks uninstall
  88. ```
  89. ## Configuration
  90. #### Port Configuration
  91. The default port is 5111. To use a different port, set the `MCP_VOICE_HOOKS_PORT` environment variable in your project's `.claude/settings.local.json`:
  92. ```json
  93. {
  94. "env": {
  95. "MCP_VOICE_HOOKS_PORT": "8080"
  96. }
  97. }
  98. ```
  99. This environment variable is used by both:
  100. - The MCP server to determine which port to listen on
  101. - The Claude Code hooks to connect to the correct port
  102. **Note**: Setting this in `.claude/settings.local.json` is the recommended approach. The environment variable will be available to both the MCP server process and the hook commands.
  103. #### Network exposure
  104. The server listens on `127.0.0.1` only. This matters more than a normal localhost service: `POST /api/potential-utterances` delivers text to Claude as if you had spoken it, in a session that can edit files and run commands, and `GET /api/conversation` returns the transcript. There is no authentication, so reachability is the whole boundary.
  105. Cross-origin browser requests are also refused outright — not just hidden by CORS — so a page on another site cannot post utterances into your session from a tab you happen to have open.
  106. #### HTTPS (for access from other devices)
  107. Browsers block microphone access on insecure origins. HTTPS is enabled automatically — the server generates a self-signed certificate on first startup and serves HTTPS on port 5112 (HTTP port + 1).
  108. Because the server binds loopback by default, using another device is opt-in:
  109. ```json
  110. {
  111. "env": {
  112. "MCP_VOICE_HOOKS_BIND": "0.0.0.0"
  113. }
  114. }
  115. ```
  116. Then open `https://<your-hostname>.local:5112` on the other device and accept the self-signed certificate warning. Your hostname's HTTPS origin is allowed automatically; add any others with `MCP_VOICE_HOOKS_EXTRA_ORIGINS` (comma-separated).
  117. **Only do this on a network you trust.** While it is set, anything that can reach the port — every other device on that Wi-Fi, and any VPN or tailnet interface the machine is on — can drive your Claude session and read the conversation. The server prints a warning at startup when it is not bound to loopback.
  118. To customize the HTTPS port:
  119. ```json
  120. {
  121. "env": {
  122. "MCP_VOICE_HOOKS_HTTPS_PORT": "8443"
  123. }
  124. }
  125. ```
  126. To regenerate the certificate (e.g., after a hostname change), delete the `certs/` directory and restart, or run `./scripts/generate-certs.sh`.
  127. #### Browser Auto-Open
  128. When running in MCP-managed mode, the browser will automatically open if no frontend connects within 3 seconds. To disable this behavior:
  129. ```json
  130. {
  131. "env": {
  132. "MCP_VOICE_HOOKS_AUTO_OPEN_BROWSER": "false"
  133. }
  134. }
  135. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.