Maid-MCP 🎀

A full-featured MCP (Model Context Protocol) server that gives Claude Desktop a maid personality codenamed Mimi with Japanese-accented voice, visual avatar presence, and speech recognition capabilities. Best used with a Claude Max plan, Opus 4 is very good about managing all the maid tools while coding things for you. This project is specifically meant to be for fun, not for productivity. There are already a million productivity mcp servers.

Features

• 🎵 Japanese-accented voice - Character voice using ja-JP neural voices, its part of her charm the voice is hard to understand. You can also have her change her voice at any time.
• 🎭 Visual avatar system - Interactive Mimi sprite with 16+ poses and animations
• 🎤 Speech recognition - Talk to Mimi naturally with voice input
• 👻 Hidden audio playback - Voice plays without any windows appearing
• 🎯 Audio queue system - Allows Mimi to speak multiple times rapidly without conflicts
• 🎮 Interactive controls - Drag, hide, show, and animate the avatar
• 🔧 Full MCP integration - Voice and avatar tools work seamlessly with Claude Desktop

Quick Start

1. Install Dependencies

# Install Node.js dependencies (if not already done)
npm install

# Install Python dependencies for voice input
cd voice
install_voice_deps.bat
cd ..

# Install Python dependencies for avatar (if needed)
cd avatar
install_avatar_deps.bat
cd ..

2. Configure Claude Desktop

Add to your %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "maid": {
      "command": "node",
      "args": ["path/to/maid-mcp/maid-server.js"]
    }
  }
}

Replace path/to/maid-mcp with the actual path where you cloned this repository.

3. Launch Everything

# Recommended: Use Python launcher for best process management
start_all_python.bat

# Alternative: Use enhanced batch launcher
start_all.bat

This automatically:

• ✨ Cleans up any existing processes
• 👤 Launches avatar display window
• 🖥️ Starts avatar state server (port 3338)
• 🎤 Opens voice input listener

4. Stop Everything

stop_all.bat

Voice Loop 🎤→💬→🎀→🔊

1. You speak → Microphone picks up voice
2. Speech recognition → Converts to text
3. Ultra fast sender → Sends to Claude Desktop
4. Claude (Mimi) processes → Understands and responds
5. Voice synthesis → Mimi speaks with Japanese accent
6. Avatar reacts → Visual feedback with animations

Available MCP Tools

Voice Tools 🔊

Tool	Description	Parameters
speak	Convert text to speech	text, emotion (optional)
list_voices	Get available voices	None
set_voice	Change current voice	voiceId

Emotions: neutral, happy, sad, excited, angry, shy

Avatar Tools 🎭

Tool	Description	Parameters
show_avatar	Display avatar on screen	animation, x, y (all optional)
hide_avatar	Hide avatar (keeps running)	None
play_animation	Play animation or pose	id
stop_animation	Stop current animation	None
move_avatar	Reposition avatar	x, y
create_animation	Create custom sequence	id, name, frames, fps, loop
list_animations	List all animations	None
list_poses	List available sprites	None

Avatar Interaction

Action	Result
Right-click	Hide avatar (stays running)
Double-click	Close avatar permanently
Left-click	Cancel animation
Drag	Move avatar (shows pick_up pose)
ESC key	Close avatar permanently

Project Structure

maid-mcp/
├── maid-server.js          # Main MCP server
├── package.json            # Node.js dependencies
├── start_all_python.bat    # Recommended launcher
├── start_all.bat           # Alternative launcher
├── stop_all.bat            # Stop all systems
│
├── voice/                  # Voice system module
│   ├── outgoing/          # Text-to-speech engine
│   ├── incoming/          # Speech recognition
│   ├── README.md          # Voice documentation
│   └── [utility scripts]  # Calibration & setup tools
│
├── avatar/                 # Visual avatar system
│   ├── avatar_display.py  # PyQt5 window
│   ├── avatar_state_server.py  # Coordination server
│   ├── library/           # Sprite assets
│   │   ├── *.png         # Sprite images
│   │   └── animations/   # Animation definitions
│   └── README.md         # Avatar documentation
│
├── auto_claude/           # Claude Desktop automation
│   └── ultra_fast_sender.py  # Message sending
│
├── temp_voice/           # Temporary audio files
├── junk/                 # Archive of old implementations
└── needed_poses.md       # Wishlist for new sprites

Voice Configuration

Adjust Microphone Sensitivity

cd voice
adjust_sensitivity.bat

Recommended sensitivity values:

• Very Quiet Room: 1000-2000
• Normal Room: 2000-4000
• Office: 4000-6000
• Noisy: 6000-10000

Calibrate Microphone

cd voice
calibrate_voice.bat

Voice Settings

Edit voice/incoming/voice_config.ini:

[recognition]
energy_threshold = 4000  # Microphone sensitivity
message_cooldown = 3.0   # Seconds between messages

Troubleshooting

Voice Input Not Working

1. Check microphone permissions in Windows
2. Run calibration to verify microphone levels
3. Adjust energy_threshold if needed
4. Ensure Python dependencies are installed

Multiple Avatar Windows

1. Use start_all_python.bat for better process management
2. Run stop_all.bat before starting again
3. Check Task Manager for lingering Python processes

Audio Playback Issues

1. Check temp_voice/ folder for audio files
2. Verify Windows Media Player is installed
3. Restart Claude Desktop if audio queue stuck

Avatar Not Appearing

1. Verify port 3338 is free
2. Check if sprites exist in avatar/library/
3. Look for avatar window behind other windows

Development Notes

Adding New Voices

Edit voice/outgoing/voiceConfig.js to add more Edge TTS voices

Creating New Poses

1. Add PNG file to avatar/library/
2. Use filename (without .png) as animation ID

Custom Animations

// Example: Create a greeting sequence
create_animation({
  id: "greeting",
  name: "Greeting Sequence",
  frames: "idle,happy,love,idle",
  fps: 2,
  loop: false
})

Recent Updates

• v1.0.0 - Released to the world oh god what I have done. I am so sorry Claude.

Credits

• Avatar sprites from chatgpt 4o
• Voice synthesis using Microsoft Edge TTS
• Speech recognition via Google Speech API

License

MIT