<div align="center">

🎤 OpenCode Voice MCP Server

Voice Input for AI Coding Assistants

Speak your prompts. No typing required.

Installation • Quick Start • Tools • Configuration • Architecture • Contributing

</div>

---

✨ Features

Feature	Description
🎤 Voice Recording	Record audio from microphone with configurable duration
🗣️ Speech-to-Text	Transcribe using local Whisper model (100% offline)
⌨️ Auto-Typing	Type transcribed text at cursor position
🔒 Privacy First	No cloud API — audio never leaves your machine
🌍 Multi-Language	Support for 99+ languages via Whisper
🔌 MCP Standard	Works with OpenCode, Claude Code, Cursor, and more

📦 Installation

# Install globally
npm install -g @opencode-ai/voice-mcp

# Or use with npx (no install required)
npx @opencode-ai/voice-mcp

Prerequisites

<details> <summary><strong>macOS</strong></summary>

# Install recording tool
brew install sox

# Install transcription engine
pip install faster-whisper

</details>

<details> <summary><strong>Linux (Ubuntu/Debian)</strong></summary>

# Install recording tool
sudo apt install sox

# Install transcription engine
pip install faster-whisper

</details>

<details> <summary><strong>Windows</strong></summary>

# Install FFmpeg (via scoop)
scoop install ffmpeg

# Install transcription engine
pip install faster-whisper

</details>

🚀 Quick Start

Step 1: Configure MCP Server

Add to your MCP config file:

Tool	Config Location
OpenCode	~/.config/opencode/config.json
Claude Code	~/.claude/claude_desktop_config.json
Cursor	~/.cursor/mcp.json

OpenCode (use mcp key):

{
  "mcp": {
    "voice": {
      "command": "npx",
      "args": ["-y", "@opencode-ai/voice-mcp"]
    }
  }
}

Claude Desktop / Cursor (use mcpServers key):

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

Step 2: Restart Your Tool

Restart OpenCode, Claude Code, or Cursor to load the MCP server.

Step 3: Use Voice Input

@voice voice_transcribe
@voice voice_type
@voice voice_status

🛠️ Tools

voice_transcribe

Record audio from microphone and transcribe to text.

{
  "name": "voice_transcribe",
  "arguments": {
    "duration": 10,
    "language": "en"
  }
}

Parameter	Type	Default	Description
duration	number	10	Recording duration in seconds
language	string	auto	Language code (e.g., en, es, fr)

Returns: Transcribed text as string.

---

voice_type

Record audio, transcribe to text, and type it at the cursor position.

{
  "name": "voice_type",
  "arguments": {
    "duration": 10,
    "language": "en"
  }
}

Parameter	Type	Default	Description
duration	number	10	Recording duration in seconds
language	string	auto	Language code

Returns: Confirmation message with typed text.

---

voice_status

Check if voice recording and transcription are available.

{
  "name": "voice_status",
  "arguments": {}
}

Returns:

{
  "recording": "rec",
  "transcription": "faster-whisper (local)",
  "platform": "darwin",
  "ready": true
}

⚙️ Configuration

Environment Variables

Variable	Description	Default
WHISPER_MODEL	Whisper model size	base
WHISPER_DEVICE	Device to use (cpu, cuda, auto)	auto
WHISPER_COMPUTE	Compute type (int8, float16, float32)	int8

Model Sizes

Model	Size	Speed	Accuracy	VRAM
tiny	~75MB	⚡⚡⚡⚡	⭐⭐	~1GB
base	~150MB	⚡⚡⚡	⭐⭐⭐	~1GB
small	~500MB	⚡⚡	⭐⭐⭐⭐	~2GB
medium	~1.5GB	⚡	⭐⭐⭐⭐⭐	~5GB
large-v3	~3GB	🐌	⭐⭐⭐⭐⭐	~10GB

Recommendation: Use base for best balance of speed and accuracy.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Client                               │
│                  (OpenCode / Claude Code / Cursor)              │
└──────────────────────────┬──────────────────────────────────────┘
                           │ JSON-RPC
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Voice MCP Server                             │
│                     (Node.js)                                   │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │ voice_record │  │voice_transcribe│ │  voice_type  │         │
│  │    Tool      │  │     Tool     │  │    Tool      │         │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘         │
│         │                 │                 │                   │
│         ▼                 ▼                 ▼                   │
│  ┌─────────────────────────────────────────────────────┐       │
│  │              Audio Recording Layer                   │       │
│  │         (sox / ffmpeg / macOS rec)                  │       │
│  └─────────────────────────┬───────────────────────────┘       │
│                            │                                    │
│                            ▼                                    │
│  ┌─────────────────────────────────────────────────────┐       │
│  │           Transcription Engine                      │       │
│  │      (faster-whisper / OpenAI API)                  │       │
│  └─────────────────────────┬───────────────────────────┘       │
│                            │                                    │
│                            ▼                                    │
│  ┌─────────────────────────────────────────────────────┐       │
│  │              Output Layer                           │       │
│  │    ┌─────────────┐  ┌─────────────────────┐        │       │
│  │    │ Return Text │  │ Type at Cursor      │        │       │
│  │    │   (MCP)     │  │ (osascript/xdotool) │        │       │
│  │    └─────────────┘  └─────────────────────┘        │       │
│  └─────────────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────────────┘

Data Flow

┌─────────┐    ┌─────────┐    ┌─────────────┐    ┌─────────┐
│  User   │───▶│  Micro- │───▶│  Whisper    │───▶│  Text   │
│  Speaks │    │  phone  │    │  Transcribe │    │  Output │
└─────────┘    └─────────┘    └─────────────┘    └─────────┘
     │              │               │                │
     │              │               │                │
     ▼              ▼               ▼                ▼
  "Hello      Records 16kHz    Processes with    Returns text
   world"     mono audio      base model        or types it

🔧 Development

Setup

# Clone repository
git clone https://github.com/YuvrajSinghBhadoria2/opencode-voice-mcp.git
cd opencode-voice-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev

Project Structure

opencode-voice-mcp/
├── src/
│   └── index.ts          # MCP server implementation
├── dist/
│   └── index.js          # Compiled output
├── package.json          # Package configuration
├── tsconfig.json         # TypeScript config
├── build.sh              # Build script
└── publish.sh            # npm publish script

Available Scripts

Command	Description
npm run build	Compile TypeScript to JavaScript
npm run dev	Run in development mode with tsx
npm run start	Run compiled server
./publish.sh	Build and publish to npm

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Add tests for new features
• Update documentation as needed
• Use conventional commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol - Standard for AI tool integration
• faster-whisper - Fast Whisper implementation
• OpenCode - AI coding assistant
• OpenAI Whisper - Speech recognition model

---

<div align="center">

Built with ❤️ for the developer community

Report Bug • Request Feature • Discussions

</div>