MMAudio

MMAudio MCP

MMAudioの高度なAI技術を使用した、AI搭載の動画から音声への変換とテキストからの音声生成です。このデスクトップ拡張機能はModel Context Protocol（MCP）を実装し、Cursor、Claude Desktop、その他のMCP対応クライアントとシームレスに連携できます。

🌟 特長

• 動画から音声を生成：AIによる分析で、動画コンテンツを同期した音声に変換します
• テキストから音声を生成：テキストの説明からプロフェッショナルな音声コンテンツを作成します
• APIキーの検証：MMAudioのAPI認証情報を確認し、アカウントの状態をチェックします
• MCPプロトコル：幅広い互換性を実現する、完全なModel Context Protocolの実装です
• エラー処理：詳細なフィードバックを備えた包括的なエラー処理です
• 型安全性：Zodスキーマ検証による完全なTypeScriptサポートです
• 設定可能：さまざまな用途に対応する柔軟な設定オプションです

🚀 クイックスタート

前提条件

• Node.js >= 18.0.0
• MMAudio APIキー（こちらから取得）
• MCP対応クライアント（Cursor、Claude Desktopなど）

インストール

1. この拡張機能をクローンまたはダウンロードします：

   cd mcp
   npm install
   

2. APIキーを設定します：

   # 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. インストールをテストします：

   npm start
   

4. パッケージをリンクします：

   npm link
   

Cursorでの使用

1. CursorのMCP設定に追加します：

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

2. Cursorを再起動すると、MMAudioのツールをAIアシスタントで利用できるようになります。

Claude Desktopでの使用

1. Claude Desktopの設定に追加します（claude_desktop_config.json）：

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

2. Claude Desktopを再起動して拡張機能を読み込みます。

🛠️ 利用可能なツール

1. 動画から音声を生成

動画コンテンツからAI搭載の音声を生成します。

ツール名：video_to_audio

パラメーター：

• video_url（必須）：動画ファイルのURL
• prompt（必須）：生成する音声の説明
• negative_prompt（任意）：生成する音声で避けたい内容
• duration（任意）：音声の長さ（秒）（1～30、デフォルト：8）
• num_steps（任意）：推論ステップ数（1～50、デフォルト：25）
• cfg_strength（任意）：ガイダンスの強度（1～10、デフォルト：4.5）
• seed（任意）：再現可能な結果を得るための乱数シード

例：

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

パラメーター：

• prompt（必須）：生成する音声の説明
• duration（任意）：音声の長さ（秒）（1～30、デフォルト：8）
• num_steps（任意）：推論ステップ数（1～50、デフォルト：25）
• cfg_strength（任意）：ガイダンスの強度（1～10、デフォルト：4.5）
• negative_prompt（任意）：生成する音声で避けたい内容
• seed（任意）：再現可能な結果を得るための乱数シード

例：

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

3. APIキーの検証

MMAudioのAPIキーを検証し、アカウントの状態を確認します。

ツール名：validate_api_key

パラメーター：

• api_key（任意）：検証するAPIキー（指定しない場合は設定済みのキーを使用します）

例：

Validate my MMAudio API key

⚙️ 設定

環境変数

変数	説明	必須	デフォルト
MMAUDIO_API_KEY	MMAudio API キー	はい	-
MMAUDIO_BASE_URL	MMAudio API のベース URL	いいえ	https://mmaudio.net
MMAUDIO_TIMEOUT	リクエストのタイムアウト（ミリ秒）	いいえ	60000
LOG_LEVEL	ログレベル（error、warn、info、debug）	いいえ	error
DEBUG	デバッグモードを有効にする	いいえ	false

設定ファイル

設定には config.js ファイルも使用できます。

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

📝 使用例

動画から音声への変換例

// 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";

テキストから音声への変換例

// 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";

🔧 開発

プロジェクト構成

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

テスト

1. サーバーを直接テストする：

   npm start
   

2. シンプルな MCP クライアントでテストする：

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

開発モード

デバッグを有効にして、サーバーを開発モードで実行します。

npm run dev

これにより、追加のログ出力とデバッグ用の Node.js インスペクターが有効になります。

🚨 トラブルシューティング

よくある問題

1.「API key is required」エラー

問題：拡張機能が API キーを見つけられません。

解決策：

• MMAUDIO_API_KEY 環境変数が設定されていることを確認します
• または、API キーを含む config.js ファイルを作成します
• API キーが正しく、有効であることを確認します

2.「Connection refused」またはネットワークエラー

問題：MMAudio API に接続できません。

解決策：

• インターネット接続を確認します
• ベース URL が正しいことを確認します
• ファイアウォールによる制限がないか確認します

3.「Insufficient credits」エラー

問題：MMAudio アカウントのクレジットが不足しています。

解決策：

• mmaudio.net/dashboard でアカウント残高を確認します
• 必要に応じてクレジットを追加購入します
• validate_api_key ツールを使用してアカウントの状態を確認します

4. MCP クライアントが拡張機能を検出しない

問題：MCP クライアント（Cursor、Claude Desktop）に MMAudio ツールが表示されません。

解決策：

• MCP クライアントの設定で構成パスを確認します
• Node.js が PATH に含まれていることを確認します
• サーバーログにエラーがないか確認します
• MCP クライアントを再起動します

デバッグモード

詳細なログを出力するには、デバッグモードを有効にします。

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

ログ

サーバーは stderr にログを出力します。ログはファイルにリダイレクトできます。

node server/index.js 2> mmaudio.log

📄 API リファレンス

レスポンス形式

すべてのツールは、次の形式でレスポンスを返します。

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

成功レスポンスの例

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

エラーレスポンスの例

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

🔒 セキュリティ

• API キーは安全に取り扱われ、ログに記録されません
• すべてのリクエストで HTTPS を使用します
• 拡張機能はサンドボックス環境で実行されます
• 機密データはローカルに保存されません

📖 関連ドキュメント

• MMAudio API ドキュメント
• Model Context Protocol 仕様
• Cursor MCP 統合ガイド
• Claude Desktop MCP セットアップ

🤝 貢献

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 該当する場合はテストを追加します
5. プルリクエストを送信します

📝 ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。

💬 サポート

• MMAudio サポート
• GitHub の問題
• ドキュメント

---

MMAudio チームが ❤️ を込めて作成