MMAudio MCP

AI-powered video-to-audio and text-to-audio generation using MMAudio's advanced AI technology. This Desktop Extension implements the Model Context Protocol (MCP) to provide seamless integration with Cursor, Claude Desktop, and other MCP-compatible clients.

🌟 Features

• Video-to-Audio Generation: Transform video content into synchronized audio with AI-powered analysis

• Text-to-Audio Generation: Create professional audio content from text descriptions

• API Key Validation: Verify MMAudio API credentials and check account status

• MCP Protocol: Full Model Context Protocol implementation for universal compatibility

• Error Handling: Comprehensive error handling with detailed feedback

• Type Safety: Full TypeScript support with Zod schema validation

• Configurable: Flexible configuration options for different use cases

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0

• MMAudio API key (Get one here)

• MCP-compatible client (Cursor, Claude Desktop, etc.)

Installation

1. Clone or download this extension:

   cd mcp npm install

2. Configure your API key:

   # Set environment variable export MMAUDIO_API_KEY="sk-your-api-key-here" # Or create a config.js file (copy from config.example.js) cp config.example.js config.js # Edit config.js with your API key

3. Test the installation:

   npm start

4. Link the package:

   npm link

Usage with Cursor

1. Add to your Cursor MCP configuration:

   { "mcpServers": { "mmaudio": { "command": "npx", "args": ["-y", "mmaudio-mcp@latest"], "env": { "MMAUDIO_API_KEY": "sk-your-api-key-here" } } } }

2. Restart Cursor and the MMAudio tools will be available in your AI assistant.

Usage with Claude Desktop

1. Add to your Claude Desktop configuration (claude_desktop_config.json):

   { "mcpServers": { "mmaudio": { "command": "npx", "args": ["-y", "mmaudio-mcp@latest"], "env": { "MMAUDIO_API_KEY": "sk-your-api-key-here" } } } }

2. Restart Claude Desktop to load the extension.

🛠️ Available Tools

1. Video-to-Audio Generation

Generate AI-powered audio from video content.

Tool Name: video_to_audio

Parameters:

• video_url (required): URL of the video file

• prompt (required): Description of the audio you want to generate

• negative_prompt (optional): What to avoid in the generated audio

• duration (optional): Audio duration in seconds (1-30, default: 8)

• num_steps (optional): Number of inference steps (1-50, default: 25)

• cfg_strength (optional): Guidance strength (1-10, default: 4.5)

• seed (optional): Random seed for reproducible results

Example:

2. Text-to-Audio Generation

Create audio content from text descriptions.

Tool Name: text_to_audio

Parameters:

• prompt (required): Description of the audio you want to generate

• duration (optional): Audio duration in seconds (1-30, default: 8)

• num_steps (optional): Number of inference steps (1-50, default: 25)

• cfg_strength (optional): Guidance strength (1-10, default: 4.5)

• negative_prompt (optional): What to avoid in the generated audio

• seed (optional): Random seed for reproducible results

Example:

3. API Key Validation

Validate your MMAudio API key and check account status.

Tool Name: validate_api_key

Parameters:

• api_key (optional): API key to validate (uses configured key if not provided)

Example:

⚙️ Configuration

Environment Variables

Configuration File

You can also use a config.js file for configuration:

📝 Example Usage

Video-to-Audio Example

Text-to-Audio Example

🔧 Development

Project Structure

Testing

1. Test the server directly:

   npm start

2. Test with a simple MCP client:

   echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | npm start

Development Mode

Run the server in development mode with debugging:

This enables additional logging and the Node.js inspector for debugging.

🚨 Troubleshooting

Common Issues

1. "API key is required" Error

Problem: The extension can't find your API key.

Solution:

• Ensure you've set the MMAUDIO_API_KEY environment variable

• Or create a config.js file with your API key

• Verify the API key is correct and active

2. "Connection refused" or Network Errors

Problem: Can't connect to MMAudio API.

Solution:

• Check your internet connection

• Verify the base URL is correct

• Check if there are any firewall restrictions

3. "Insufficient credits" Error

Problem: Your MMAudio account doesn't have enough credits.

Solution:

• Check your account balance at mmaudio.net/dashboard

• Purchase additional credits if needed

• Use the validate_api_key tool to check your account status

4. MCP Client Not Detecting Extension

Problem: Your MCP client (Cursor, Claude Desktop) doesn't show MMAudio tools.

Solution:

• Verify the configuration path in your MCP client settings

• Ensure Node.js is in your PATH

• Check the server logs for errors

• Restart your MCP client

Debug Mode

Enable debug mode for detailed logging:

Logs

The server logs to stderr. You can redirect logs to a file:

📄 API Reference

Response Format

All tools return responses in this format:

Success Response Example

Error Response Example

🔒 Security

• API keys are handled securely and not logged

• All requests use HTTPS

• The extension runs in a sandboxed environment

• No sensitive data is stored locally

📖 Related Documentation

• MMAudio API Documentation

• Model Context Protocol Specification

• Cursor MCP Integration Guide

• Claude Desktop MCP Setup

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

📝 License

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

💬 Support

• MMAudio Support

• GitHub Issues

• Documentation

Made with ❤️ by the MMAudio Team