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

Clone or download this extension:
```
cd mcp
npm install
```

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

Test the installation:
```
npm start
```
Link the package:
```
npm link
```

Usage with Cursor

Add to your Cursor MCP configuration:

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

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

Usage with Claude Desktop

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"
      }
    }
  }
}

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:

Generate audio for this video: https://example.com/video.mp4 with the prompt "peaceful forest sounds with birds chirping and gentle wind"

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:

Create audio with the description "coffee shop ambiance with gentle chatter and espresso machine sounds"

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:

Validate my MMAudio API key

⚙️ Configuration

Environment Variables

Variable	Description	Required	Default
`MMAUDIO_API_KEY`	Your MMAudio API key	Yes	-
`MMAUDIO_BASE_URL`	Base URL for MMAudio API	No	`https://mmaudio.net`
`MMAUDIO_TIMEOUT`	Request timeout in milliseconds	No	`60000`
`LOG_LEVEL`	Log level (error, warn, info, debug)	No	`error`
`DEBUG`	Enable debug mode	No	`false`

Configuration File

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

export const config = {
  apiKey: "sk-your-api-key-here",
  baseUrl: "https://mmaudio.net",
  timeout: 60000,
  // ... other options
};

📝 Example Usage

Video-to-Audio Example

// In your MCP client (Cursor, Claude Desktop, etc.)
"Please generate audio for this video URL: https://example.com/nature_video.mp4";
"I want forest sounds with birds chirping and a gentle breeze";
"Duration should be 10 seconds";

Text-to-Audio Example

// Create ambient audio
"Generate 15 seconds of coffee shop ambiance with gentle background chatter";

// Create sound effects
"Create the sound of rain falling on a wooden roof for 8 seconds";

// Create atmospheric audio
"Generate futuristic sci-fi ambient sounds for a space station";

🔧 Development

Project Structure

mcp/
├── server/index.js              # Main MCP server implementation
├── package.json           # Node.js dependencies and scripts
├── manifest.json          # DXT extension manifest
├── config.example.js      # Configuration example
└── README.md              # This file

Testing

Test the server directly:
```
npm start
```

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:

npm run dev

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:

DEBUG=true MMAUDIO_API_KEY=your-key node server/index.js

Logs

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

node server/index.js 2> mmaudio.log

📄 API Reference

Response Format

All tools return responses in this format:

{
  "content": [
    {
      "type": "text",
      "text": "{\"success\": true, \"message\": \"...\", \"result\": {...}}"
    }
  ]
}

Success Response Example

{
  "success": true,
  "message": "Audio generated successfully from text",
  "result": {
    "audio_url": "https://example.com/generated_audio.wav",
    "content_type": "audio/wav",
    "file_name": "generated_audio.wav",
    "file_size": 1024000,
    "duration": 8,
    "prompt": "coffee shop ambiance"
  }
}

Error Response Example

{
  "success": false,
  "error": "Invalid API key. Please check your MMAudio API key.",
  "code": "INVALID_REQUEST"
}

🔒 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

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📝 License

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

💬 Support

Made with ❤️ by the MMAudio Team

MMAudio MCP

🌟 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

Clone or download this extension:
```
cd mcp
npm install
```

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

Test the installation:
```
npm start
```
Link the package:
```
npm link
```

Usage with Cursor

Add to your Cursor MCP configuration:

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

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

Usage with Claude Desktop

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"
      }
    }
  }
}

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:

Generate audio for this video: https://example.com/video.mp4 with the prompt "peaceful forest sounds with birds chirping and gentle wind"

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:

Create audio with the description "coffee shop ambiance with gentle chatter and espresso machine sounds"

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:

Validate my MMAudio API key

⚙️ Configuration

Environment Variables

Variable	Description	Required	Default
`MMAUDIO_API_KEY`	Your MMAudio API key	Yes	-
`MMAUDIO_BASE_URL`	Base URL for MMAudio API	No	`https://mmaudio.net`
`MMAUDIO_TIMEOUT`	Request timeout in milliseconds	No	`60000`
`LOG_LEVEL`	Log level (error, warn, info, debug)	No	`error`
`DEBUG`	Enable debug mode	No	`false`

Configuration File

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

export const config = {
  apiKey: "sk-your-api-key-here",
  baseUrl: "https://mmaudio.net",
  timeout: 60000,
  // ... other options
};

📝 Example Usage

Video-to-Audio Example

// In your MCP client (Cursor, Claude Desktop, etc.)
"Please generate audio for this video URL: https://example.com/nature_video.mp4";
"I want forest sounds with birds chirping and a gentle breeze";
"Duration should be 10 seconds";

Text-to-Audio Example

// Create ambient audio
"Generate 15 seconds of coffee shop ambiance with gentle background chatter";

// Create sound effects
"Create the sound of rain falling on a wooden roof for 8 seconds";

// Create atmospheric audio
"Generate futuristic sci-fi ambient sounds for a space station";

🔧 Development

Project Structure

mcp/
├── server/index.js              # Main MCP server implementation
├── package.json           # Node.js dependencies and scripts
├── manifest.json          # DXT extension manifest
├── config.example.js      # Configuration example
└── README.md              # This file

Testing

Test the server directly:
```
npm start
```

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:

npm run dev

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:

DEBUG=true MMAUDIO_API_KEY=your-key node server/index.js

Logs

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

node server/index.js 2> mmaudio.log

📄 API Reference

Response Format

All tools return responses in this format:

{
  "content": [
    {
      "type": "text",
      "text": "{\"success\": true, \"message\": \"...\", \"result\": {...}}"
    }
  ]
}

Success Response Example

{
  "success": true,
  "message": "Audio generated successfully from text",
  "result": {
    "audio_url": "https://example.com/generated_audio.wav",
    "content_type": "audio/wav",
    "file_name": "generated_audio.wav",
    "file_size": 1024000,
    "duration": 8,
    "prompt": "coffee shop ambiance"
  }
}

Error Response Example

{
  "success": false,
  "error": "Invalid API key. Please check your MMAudio API key.",
  "code": "INVALID_REQUEST"
}

🔒 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

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📝 License

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

💬 Support

Made with ❤️ by the MMAudio Team

MMAudio MCP

MMAudio MCP

🌟 Features

🚀 Quick Start

Prerequisites

Installation

Usage with Cursor

Usage with Claude Desktop

🛠️ Available Tools

1. Video-to-Audio Generation

2. Text-to-Audio Generation

3. API Key Validation

⚙️ Configuration

Environment Variables

Configuration File

📝 Example Usage

Video-to-Audio Example

Text-to-Audio Example

🔧 Development

Project Structure

Testing

Development Mode

🚨 Troubleshooting

Common Issues

1. "API key is required" Error

2. "Connection refused" or Network Errors

3. "Insufficient credits" Error

4. MCP Client Not Detecting Extension

Debug Mode

Logs

📄 API Reference

Response Format

Success Response Example

Error Response Example

🔒 Security

📖 Related Documentation

🤝 Contributing

📝 License

💬 Support

MMAudio MCP

🌟 Features

🚀 Quick Start

Prerequisites

Installation

Usage with Cursor

Usage with Claude Desktop

🛠️ Available Tools

1. Video-to-Audio Generation

2. Text-to-Audio Generation

3. API Key Validation

⚙️ Configuration

Environment Variables

Configuration File

📝 Example Usage

Video-to-Audio Example

Text-to-Audio Example

🔧 Development

Project Structure

Testing

Development Mode

🚨 Troubleshooting

Common Issues

1. "API key is required" Error

2. "Connection refused" or Network Errors

3. "Insufficient credits" Error

4. MCP Client Not Detecting Extension

Debug Mode

Logs

📄 API Reference

Response Format

Success Response Example

Error Response Example

🔒 Security

📖 Related Documentation

🤝 Contributing

📝 License

💬 Support