🎵 Muzaic MCP Server

Official MCP server for Muzaic AI — generate custom music for video content

<!-- mcp-name: io.github.muzaic-ai/muzaic-mcp -->

---

✨ What is this?

Muzaic MCP Server connects the Muzaic AI music generation API to any LLM or agent that speaks the Model Context Protocol (MCP). Generate AI-powered soundtracks for videos — directly from Claude, Cursor, VS Code, or any MCP client.

• 🎶 Generate single tracks or multi-region soundtracks
• 🏷️ Browse 30+ music tags (style, mood, genre, cultural)
• 🎛️ Fine-tune with 5 parameters: intensity, tempo, rhythm, tone, variance
• 📈 Dynamic keyframes for parameter changes over time
• ✅ Tag compatibility validation
• 💰 Check account balance and token usage

⚠️ Note: Muzaic tokens are needed to generate music. Get your API key from adminpanel.muzaic.ai.

---

📦 Quick Install

pip install muzaic-mcp

Or with uv:

uv pip install muzaic-mcp

---

🏃 Quick Start

export MUZAIC_API_KEY=your_api_key_here
muzaic-mcp

---

🔧 Configuration

Claude Desktop

Go to Claude → Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "Muzaic": {
      "command": "uvx",
      "args": ["muzaic-mcp"],
      "env": {
        "MUZAIC_API_KEY": "<your-api-key>"
      }
    }
  }
}

Cursor

Windows: Add to %USERPROFILE%\.cursor\mcp.json (e.g., C:\Users\YourName\.cursor\mcp.json)

macOS/Linux: Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "Muzaic": {
      "command": "uvx",
      "args": ["muzaic-mcp"],
      "env": {
        "MUZAIC_API_KEY": "<your-api-key>"
      }
    }
  }
}

Note: If uvx is not in your PATH, use the full path. On Windows with Python installed, you can find it with:

where.exe uvx
# Or if using uv:
where.exe uv
# Then use: "C:\\path\\to\\uv.exe" with args: ["tool", "run", "muzaic-mcp"]

Alternatively, if you have Python installed, you can use:

{
  "mcpServers": {
    "Muzaic": {
      "command": "python",
      "args": ["-m", "muzaic_mcp.server"],
      "env": {
        "MUZAIC_API_KEY": "<your-api-key>"
      }
    }
  }
}

Claude Code

claude mcp add-json "Muzaic" '{"command":"uvx","args":["muzaic-mcp"],"env":{"MUZAIC_API_KEY":"<your-api-key>"}}'

VS Code

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "Muzaic": {
      "command": "uvx",
      "args": ["muzaic-mcp"],
      "env": {
        "MUZAIC_API_KEY": "<your-api-key>"
      }
    }
  }
}

---

🛠️ Available Tools

Tool	Description	Cost
muzaic_get_tags	List all available music tags with descriptions	Free
muzaic_validate_tags	Check tag combination compatibility	Free
muzaic_account_info	Check token balance and usage	Free
muzaic_generate_music	Generate a single AI music track	1 token/sec
muzaic_create_soundtrack	Create multi-region soundtrack with different styles	1 token/sec
muzaic_regenerate	Regenerate music from a previous hash	1 token/sec

---

💬 Example Prompts

Try these with Claude, Cursor, or any MCP client:

• "What music styles can you generate with Muzaic?"
• "Create a 60-second upbeat pop track for a product video"
• "Generate a cinematic soundtrack that starts calm and builds to epic over 2 minutes"
• "Make a 30-second chill ambient track for a meditation app intro"
• "Create a soundtrack with 3 sections: calm intro, energetic middle, peaceful outro"

---

🎛️ Music Parameters

All parameters range from 1 (low) to 9 (high):

Parameter	1	9
intensity	Calm, ambient	High energy, powerful
tempo	Very slow	Very fast
rhythm	Simple, steady	Complex patterns
tone	Dark, moody	Bright, cheerful
variance	Repetitive	Diverse, changing

Dynamic Keyframes

All parameters except tempo support keyframes — values that change over the duration of the track. Positions are expressed as percentages (0–100%) of the track duration.

# 30-second track: intensity drops at 10s, then rises to max at the end
intensity: [[0, 5], [33, 1], [100, 9]]
          ↑ start at 5  ↑ drop to 1 at 33% (=10s)  ↑ rise to 9 at 100% (=30s)

Tempo only accepts a static value (1–9) — keyframes are not supported for tempo.

---

🐛 Troubleshooting

API key not set

Error: MUZAIC_API_KEY is not set

Make sure the MUZAIC_API_KEY environment variable is configured in your MCP client settings.

uvx not found

Windows:

# Find uvx location
where.exe uvx

# If not found, install uv first:
# pip install uv
# Or download from: https://github.com/astral-sh/uv/releases

# Then use full path in mcp.json:
# "command": "C:\\Users\\YourName\\AppData\\Local\\Programs\\uv\\uv.exe"
# "args": ["tool", "run", "muzaic-mcp"]

macOS/Linux:

# Find uvx location
which uvx

# If not found, install uv:
# curl -LsSf https://astral.sh/uv/install.sh | sh

# Then use full path in config:
# "command": "/usr/local/bin/uvx"

Alternative: Use Python directly if uvx is unavailable:

{
  "mcpServers": {
    "Muzaic": {
      "command": "python",
      "args": ["-m", "muzaic_mcp.server"],
      "env": {
        "MUZAIC_API_KEY": "<your-api-key>"
      }
    }
  }
}

Timeout on long tracks

Music generation can take up to 5 minutes for 20-minute tracks. This is normal. If using MCP Inspector in dev mode, you may see timeout errors even though the generation completes.

---

🧪 Development

# Clone
git clone https://github.com/MUZAIC-Organization/muzaic-mcp.git
cd muzaic-mcp

# Install with dev dependencies
uv sync
# Or with pip:
# pip install -e ".[dev]"

# Run in dev mode
# Windows PowerShell:
$env:MUZAIC_API_KEY="your_key"
# macOS/Linux:
export MUZAIC_API_KEY=your_key

uv run mcp dev muzaic_mcp/server.py
# Or with pip:
# python -m muzaic_mcp.server

# Run tests
uv run pytest
# Or with pip:
# pytest

Local Development Setup

If you're developing locally and want to test without publishing to PyPI:

Windows:

# Install in editable mode
pip install -e .

# Test the command
$env:MUZAIC_API_KEY="your_key"
muzaic-mcp

macOS/Linux:

# Install in editable mode
pip install -e .

# Test the command
export MUZAIC_API_KEY=your_key
muzaic-mcp

Testing with MCP Inspector

npx @modelcontextprotocol/inspector
# → Transport: stdio
# → Command: uv run muzaic-mcp
# Or: python -m muzaic_mcp.server

Windows Note: If you encounter issues with npx, ensure Node.js is installed and in your PATH. You can also use the full path to npx if needed.

---

📄 License

MIT — see LICENSE for details.

---

🔗 Links

• Website: muzaic.ai
• API Docs: docs.muzaic.ai
• Get API Key: adminpanel.muzaic.ai
• Support: service@muzaic.ai