đŸŽ€AgentVibes
Back to Blog

Complete Guide to Setting Up AgentVibes with MCP in Claude Code & Claude Desktop

Step-by-step instructions for configuring the AgentVibes MCP server in Claude Code and Claude Desktop. Enable natural language voice control for your AI assistant.

tutorialmcpinstallationclaude-codeclaude-desktop

By Paul Preibisch

Why AgentVibes Transforms Your Workflow

Imagine working on a complex coding problem—you're deep in flow, fingers flying across the keyboard, when Claude responds to your query. Instead of breaking your concentration to read text, Claude speaks to you with a voice and personality you chose. "I've found that bug for you, checking the authentication module now..."

This is the power of AgentVibes. By adding voice acknowledgments and completion messages to your AI assistant, you stay in the zone. No context switching, no breaking focus—just seamless collaboration with an AI that talks back.

How does it work? In Claude Code, AgentVibes uses a custom output style that wraps around Claude's responses. When you activate the AgentVibes output style, it intercepts Claude's messages and triggers the TTS engine to speak acknowledgments when tasks start and completion messages when they finish. That's the real magic—the AgentVibes code intelligently knows when to speak.

The Model Context Protocol (MCP) adds convenience on top of this. MCP is a standardized way for AI assistants to connect with external tools and services. Instead of remembering specific slash commands to configure AgentVibes, you can simply tell Claude what you want in natural language:

  • "Switch to Aria voice"
  • "Change personality to sarcastic"
  • "Use a pirate voice for this session"

So MCP doesn't create the voice responses—the AgentVibes output style does that. MCP just makes controlling AgentVibes easier and enables it to work in Claude Desktop (which doesn't have output styles).

Two Ways to Use AgentVibes

AgentVibes works with both Claude Code (the CLI tool for developers) and Claude Desktop (the desktop application). The setup process differs slightly for each:

Claude Code Setup

Claude Code users get the easiest experience—a single command installs everything you need.

Claude Desktop Setup

Claude Desktop requires a bit more configuration, but the payoff is huge: a fully voice-enabled AI assistant for all your tasks, not just coding.

Let's walk through both setups step by step.

Setting Up AgentVibes in Claude Code

Claude Code has built-in support for AgentVibes through both slash commands AND the MCP server. The quickest way to get started is with the automated installer.

Step 1: Install AgentVibes

Open your terminal and run:

npx agentvibes install

This single command automatically installs:

  • All AgentVibes slash commands in .claude/commands/
  • Voice management hooks in .claude/hooks/
  • 19 built-in personalities (pirate, sarcastic, zen, and more)
  • The AgentVibes output style for voice acknowledgments

What happens behind the scenes? The installer creates a complete directory structure in your project's .claude/ folder, sets up audio playback scripts, and configures Claude Code to use voice responses.

Step 2: Add the MCP Server (Optional but Recommended)

While the slash commands work great, adding the MCP server unlocks natural language control. Instead of typing /agent-vibes:switch Aria, you can simply say "switch to Aria voice."

Add this to your .mcp.json configuration file:

{
  "mcpServers": {
    "agentvibes": {
      "command": "npx",
      "args": ["-y", "agentvibes@beta", "agentvibes-mcp-server"],
      "env": {
        "ELEVENLABS_API_KEY": "${ELEVENLABS_API_KEY}"
      }
    }
  }
}

Where is this file? In your project root, or in ~/.claude/.mcp.json for global configuration.

Don't have an ElevenLabs API key? Get one here with our affiliate link. Or, if you'd rather use free TTS voices, we've got you covered with Piper (see below).

Step 3: Restart Claude Code

After adding the MCP configuration, restart Claude Code to load the MCP server:

# Restart Claude Code with MCP config
claude --mcp-config .mcp.json

Step 4: Test It Out

Try a natural language command:

You: "Switch to Northern Terry voice"
Claude: "Switching to Northern Terry voice..." 🔊

You should hear Claude respond! If you don't hear anything, check the troubleshooting section below.

Setting Up AgentVibes in Claude Desktop

Claude Desktop setup requires a few prerequisites, but once configured, you'll have a voice-enabled AI assistant for everything—emails, writing, research, and more.

Prerequisites

Before starting, open PowerShell and verify you have the required software installed:

  1. Python 3.8 or higher installed

    • Check by typing in PowerShell:
    python --version

  2. Node.js and npm installed

    • Check by typing in PowerShell:
    node --version
npm --version

  3. Claude Desktop installed

  4. An audio player (usually pre-installed):

    • macOS: afplay (built-in)
    • Linux: aplay, paplay, or ffplay
    • Windows: The setup uses PowerShell's audio capabilities

Step 1: Install Required Dependencies

AgentVibes needs a few Python packages to work its magic:

# Install the AgentVibes package and MCP dependencies
pip install agentvibes anthropic-mcp-client

# For ElevenLabs voices (premium, requires API key)
# Get your API key at https://try.elevenlabs.io/agentvibes
pip install elevenlabs

# For Piper TTS (free, offline voices)
pip install piper-tts

What's the difference?

  • ElevenLabs: Premium AI voices with incredible quality and emotional range. Requires a paid API key.
  • Piper: Free, offline text-to-speech with decent quality. Perfect for getting started or working without internet.

Step 2: Get Your Audio Provider Set Up

Option A: ElevenLabs (Premium Voices)

  1. Click here to sign up at ElevenLabs with our affiliate link
  2. Copy your API key from the dashboard
  3. Set it as an environment variable:

macOS/Linux:

echo 'export ELEVENLABS_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell):

[Environment]::SetEnvironmentVariable("ELEVENLABS_API_KEY", "your-api-key-here", "User")

Option B: Piper (Free Voices)

Piper works out of the box after installation—no API key needed! It downloads voices on-demand the first time you use them.

Step 3: Configure Claude Desktop

Now comes the important part: telling Claude Desktop about the AgentVibes MCP server.

Find your Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Edit the configuration file and add the AgentVibes MCP server:

{
  "mcpServers": {
    "agentvibes": {
      "command": "npx",
      "args": ["-y", "agentvibes@beta", "agentvibes-mcp-server"],
      "env": {
        "ELEVENLABS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Important notes:

  • Replace "your-api-key-here" with your actual ElevenLabs API key
  • If using Piper (free voices), you can omit the env section entirely
  • Make sure the JSON is valid (no trailing commas, proper quotes)

Don't want to edit JSON manually? You can use the AgentVibes helper:

npx agentvibes configure-desktop

This interactive tool will guide you through the configuration process.

Step 4: Restart Claude Desktop

Close Claude Desktop completely and restart it. The MCP server should now be loaded.

How to verify it's working:

  1. Open Claude Desktop
  2. Look for a small plug or connection icon in the interface (indicates MCP servers are connected)
  3. Try asking: "What MCP tools are available?"

Claude should list AgentVibes in the available tools.

Step 5: Test Your Voice Setup

Try it out with a natural language command:

You: "Switch to Aria voice and use a friendly personality"
Claude: "Switching to Aria with a friendly personality!" 🔊

You should hear Claude respond in the Aria voice!

Choosing Your Voice Provider

AgentVibes supports two TTS providers, each with its own strengths:

ElevenLabs (Premium)

Pros:

  • Exceptional voice quality with natural emotional range
  • 150+ professional voices across 30+ languages
  • Voices sound genuinely human
  • Great for professional work and presentations

Cons:

Best for: Professional developers, content creators, anyone who values audio quality

Get started with ElevenLabs

Piper TTS (Free)

Pros:

  • Completely free and open-source
  • Works offline (no internet required)
  • No API keys or subscriptions
  • Good quality for a free option

Cons:

  • Less natural than ElevenLabs
  • Smaller voice selection
  • Less emotional range

Best for: Students, hobbyists, offline development, budget-conscious users

Switch providers anytime:

# In Claude Code
/agent-vibes:provider switch piper
/agent-vibes:provider switch elevenlabs

# Or just ask Claude
"Switch to Piper for free voices"

Next Steps: Exploring AgentVibes Features

Now that you've got AgentVibes set up, here are some powerful features to explore:

Voice Management

# List all available voices
/agent-vibes:list

# Preview voices before choosing
/agent-vibes:preview

# Switch to a specific voice
/agent-vibes:switch "Northern Terry"

Personality Modes

Make Claude speak with character! Choose from 19 built-in personalities:

# See all personalities
/agent-vibes:personality list

# Popular choices
/agent-vibes:personality pirate    # "Arr matey, I'll fix that bug!"
/agent-vibes:personality sarcastic # "Oh great, another merge conflict..."
/agent-vibes:personality zen       # "Let us mindfully debug this code..."

Language Learning Mode

Enable bilingual responses—perfect for learning a new language while coding:

/agent-vibes:learn enable
/agent-vibes:language spanish
/agent-vibes:target spanish

Now Claude speaks acknowledgments in your native language and completions in your target language!

Project-Specific Settings

Each project can have its own voice and personality. Settings are saved in the project's .claude/ directory, so your work voice stays at work and your fun voice stays in personal projects.

Troubleshooting Common Issues

No Audio Playing

Check your audio player:

# macOS
which afplay

# Linux
which aplay || which paplay

# If missing, install:
# Ubuntu/Debian
sudo apt-get install alsa-utils

# Fedora
sudo dnf install alsa-utils

Check your API key (if using ElevenLabs):

echo $ELEVENLABS_API_KEY

Should print your API key. If it's empty, the environment variable isn't set correctly.

Try a test command:

# In Claude Code
/agent-vibes:sample Aria

# This should play a test audio clip

MCP Server Not Loading

Claude Code:

  1. Check your .mcp.json file exists and has valid JSON
  2. Restart Claude Code with: claude --mcp-config .mcp.json
  3. Look for error messages on startup

Claude Desktop:

  1. Check the configuration file path is correct for your OS
  2. Verify JSON syntax (use a JSON validator online)
  3. Check Claude Desktop logs:
    • macOS: ~/Library/Logs/Claude/
    • Windows: %APPDATA%\Claude\logs\
    • Linux: ~/.config/Claude/logs/

Commands Not Working

Slash commands not found? Reinstall:

npx agentvibes install --yes

Natural language commands not working? The MCP server might not be loaded. Check the MCP troubleshooting steps above.

"Module not found" Errors

Make sure all dependencies are installed:

pip install --upgrade agentvibes anthropic-mcp-client elevenlabs piper-tts

Advanced: Multiple Projects with Different Voices

Want different voices for different types of work? AgentVibes uses project-local settings stored in .claude/:

Work project (professional voice):

cd ~/work/important-client
/agent-vibes:switch "Professional Sarah"
/agent-vibes:personality normal

Personal project (fun voice):

cd ~/personal/game-project
/agent-vibes:switch "Cowboy Bob"
/agent-vibes:personality pirate

Each project remembers its settings independently!

Getting Help

If you're still having issues:

  1. Check the GitHub Issues: AgentVibes Issues
  2. Read the full docs: AgentVibes Documentation
  3. Open a new issue: Include your OS, Claude version, and error messages

What's Next?

Explore more AgentVibes capabilities:

Ready to transform your AI workflow? Install AgentVibes now and give your AI assistant a voice!

npx agentvibes install

Ready to give your AI a voice?

Install AgentVibes in seconds and start coding with personality

Get StartedRead More Posts