@amana/mcp-qosmo

MCP (Model Context Protocol) server for the amana Qosmo service — an AI-powered background music generation service that analyzes video content and creates matching BGM.

Overview

This package exposes the Qosmo API as MCP tools, allowing AI agents to trigger music generation jobs and track their status via natural language.

Installation

npm install @amana/mcp-qosmo
# or
npx @amana/mcp-qosmo

Requirements

| Environment Variable | Description | Required | |---|---|---| | AMANA_API_KEY | Your amana platform API key | ✅ | | AMANA_API_BASE_URL | Base URL of the amana gateway | ✅ |

Configuration

Claude Desktop / Cursor

Add to your claude_desktop_config.json or Cursor MCP settings:

{
  "mcpServers": {
    "amana-qosmo": {
      "command": "npx",
      "args": ["@amana/mcp-qosmo"],
      "env": {
        "AMANA_API_KEY": "amana_key_xxxxxxxx",
        "AMANA_API_BASE_URL": "https://api.amana.io"
      }
    }
  }
}

Compy

In Compy's MCP configuration panel, add:

• Command: npx @amana/mcp-qosmo
• Env: Set AMANA_API_KEY and AMANA_API_BASE_URL

Available Tools

| Tool Name | Description | |---|---| | qosmo_create_music_job | Analyze a video and auto-generate matching BGM | | qosmo_get_job_status | Check the status of a music generation job |

Music Styles

The qosmo_create_music_job tool supports the following styles:

| Style | Description | |---|---| | ambient | Calm, atmospheric background music | | upbeat | Energetic and lively tracks | | cinematic | Epic, film-score style music | | dramatic | Intense and emotionally driven | | minimal | Simple, unobtrusive background |

Example Usage (Natural Language)

"Generate upbeat background music for my product video at https://cdn.example.com/promo.mp4, 60 seconds"

"Check the status of music generation job job_abc123"

Workflow

1. Create job → qosmo_create_music_job (returns job_id)
2. Poll status → qosmo_get_job_status (check until status = "completed")
3. Download audio from result URL

Related Packages

• @amana/mcp-files — Upload video files to amana storage
• @amana/mcp-shelf — Manage digital assets in amana Shelf

License

MIT © amana Inc.