morphclaude-senses

Give Claude ears, a voice, and eyes.

MCP server that connects Claude Code to local audio hardware.
Works with a POLY HUD wearable headset or any laptop mic and speaker.

npm install -g morphclaude-senses
morphclaude-setup

What It Adds to Claude

| Tool | Description | |------|-------------| | listen | Record from the microphone until silence. Returns transcript. | | speak | Synthesize text with Piper TTS and play through speaker. | | see | Capture a JPEG from the POLY HUD camera. Returns image. |

Everything is local. Your voice never leaves your machine.

Quick Start

All steps below run in a regular terminal — not inside Claude Code.
Open Claude Code only at the end, after setup is complete.

1. Install

npm install -g morphclaude-senses

2. Run setup wizard

morphclaude-setup

Run this in your terminal. It is an interactive wizard — do not run it inside Claude Code.

The wizard handles:

• Claude connection (Pro/Max subscription or API key)
• Audio device selection (headset or laptop)
• Push-to-talk key configuration
• Voice model download (~65 MB)
• Config written to ~/.config/morphclaude/.env

3. Add to .mcp.json

The wizard prints the exact snippet. Paste it into ~/.mcp.json (global, works in every project) or <project>/.mcp.json (one project only):

{
  "mcpServers": {
    "morphclaude-senses": {
      "command": "/usr/local/bin/morphclaude-senses"
    }
  }
}

4. Open Claude Code

claude

Claude Code reads .mcp.json on startup and launches the MCP server automatically in the background. Claude now has listen, speak, and (with a POLY HUD headset) see.

Try it:

listen to me and reply out loud

Press Page Up to start recording, speak, press again to send.

No Headset? No Problem.

ALSA mode uses your laptop's built-in mic and speakers.
Select No headset in morphclaude-setup — everything else is the same.

POLY HUD Headset Mode

The POLY HUD is a wearable ESP32 device with mic, speaker, OLED display, and camera — all on WiFi. It gives Claude a physical form factor.

First-time headset setup:

1. Power on → headset broadcasts a WiFi hotspot (SSID on OLED)
2. Join that hotspot on your laptop
3. Open: http://192.168.4.1/provision?ssid=YourWiFi&pw=YourPassword
4. Headset reboots into your home network and shows its IP on the OLED
5. Re-join your home WiFi on the laptop

Then run morphclaude-setup, select POLY HUD, and enter the IP.

Architecture

Claude Code
    │
    ├── listen() ──► audio_sidecar.py ──► faster-whisper ──► transcript
    ├── speak()  ──► audio_sidecar.py ──► Piper TTS ──► speaker
    └── see()    ──► http://<polyhud>/capture ──► JPEG image

The Node.js MCP server starts a Python sidecar on first use. Whisper and Piper load once and stay in memory — subsequent calls are fast.

Configuration

Config at ~/.config/morphclaude/.env. Edit and save — restart Claude Code to reload.

LLM_BACKEND=claude-code        # claude-code | api
ANTHROPIC_API_KEY=             # only for api mode
AUDIO_BACKEND=alsa             # alsa | polyhud
POLYHUD_IP=polyhud.local       # headset IP (polyhud mode)
ALSA_MIC_DEVICE=               # device index, blank = default
ALSA_SPK_DEVICE=               # device index, blank = default
PIPER_MODEL=/path/to/voice.onnx
WHISPER_MODEL=base             # base | small | large-v3
PTT_KEY=pageup                 # pageup | f9 | f8 | (blank = VAD)
PTT_MODE=toggle                # toggle | hold

System Requirements

• Linux (Ubuntu 22.04+)
• Node.js 18+
• Python 3.10+
• 4 GB RAM
• NVIDIA GPU optional (speeds up speech recognition 10×, enables large-v3)

Python packages (installed by morphclaude-setup):

pip install piper-tts faster-whisper sounddevice numpy scipy

Full Documentation

Complete guide including GPU setup, Blender integration, PTT troubleshooting:
INSTALL.md on GitHub

Source: github.com/cklam12345/morphClaude

MIT License