Soundraw Game BGM MCP Server

An MCP (Model Context Protocol) server that enables AI agents to generate game background music. Uses DeepSeek for intelligent scene analysis and parameter generation, and Soundraw B2B API V3 for actual music generation.

🎶 Why Game Developers ❤️ This

Modern games use dynamic, adaptive music — but composing custom BGM is costly and time-consuming.
soundraw-game-bgm automates composition by analyzing your game scenes and generating royalty-free background music that fits the mood and gameplay context.

It even outputs ready-to-use integration code for Unity and Unreal Engine so you can drop the track in with no extra engineering work.

Architecture

Game Dev Agent (Claude/Cursor)
    ↓ calls MCP tool
MCP Server (soundraw-game-bgm)
    ↓ uses DeepSeek API for reasoning
DeepSeek analyzes game context
    ↓ generates Soundraw parameters (moods, genres, themes, tempo, energy)
Soundraw API generates actual music
    ↓ async: returns request_id → poll for result
Game Dev Agent receives share_link + audio_url

Features

• Cost-Optimized: Uses DeepSeek (~90% cheaper than Claude) for scene analysis
• 4 MCP Tools: Full suite for game audio needs
• Real Soundraw API: Uses B2B API V3 with proper async handling
• Engine Integration: Auto-generated code snippets for Unreal, Unity, and Godot
• Adaptive Audio: Stem muting for dynamic game audio layers

Installation

git clone https://github.com/yksanjo/soundraw-game-bgm.git
cd soundraw-game-bgm
npm install
npm run build

Configuration

Create a .env file:

DEEPSEEK_API_KEY=sk-your-deepseek-api-key
SOUNDRAW_API_KEY=your-soundraw-bearer-token

Testing API Connections

Before using the MCP server, verify your API keys work:

# Quick test (checks API connections only)
npm run test:apis

# Full test (generates a 10-second track - uses API credits)
npm run test:apis:full

Expected output:

🎮 Soundraw Game BGM MCP Server - API Test

==================================================
Testing DeepSeek API
==================================================
API Key: sk-xxxxxx...
✅ DeepSeek Response: "DeepSeek OK"

==================================================
Testing Soundraw API Connection
==================================================
API Key: xxxxxxxxxx...
✅ Soundraw Account: Number of queries: X from ...

==================================================
Testing Soundraw Tags Endpoint
==================================================
✅ Available genres for "Epic" mood: Orchestra, Electronica...
✅ Available themes: Gaming, Cinematic...

==================================================
Test Summary
==================================================
✅ DeepSeek API
✅ Soundraw Connection
✅ Soundraw Tags
❌ Music Generation (skipped without --full flag)

🎉 Core APIs working! Ready to use the MCP server.

MCP Tools

1. generate_bgm

Generate background music based on game scene description.

Input:

{
  "scene": "boss_fight",
  "game_genre": "dark_souls_like",
  "intensity": "high",
  "mood": "epic",
  "duration_seconds": 60,
  "engine": "unreal",
  "file_format": "m4a"
}

Output:

{
  "share_link": "https://soundraw.io/edit_music?m=...",
  "audio_url": "https://..../final_xxx.m4a",
  "request_id": "...",
  "duration_seconds": 60,
  "bpm": 140,
  "timestamps": [{"start": 0, "end": 15, "energy": "Low"}, ...],
  "file_format": "m4a",
  "integration_code": "// Unreal Engine 5 integration...",
  "deepseek_reasoning": "Boss fights need epic orchestral...",
  "soundraw_params": {"moods": ["Epic", "Dark"], "genres": ["Orchestra"], ...}
}

2. get_bgm_variations

Generate variations of existing BGM.

Input:

{
  "share_link": "https://soundraw.io/edit_music?m=...",
  "variation_type": "similar",
  "length": 60
}

Or customize energy/stems:

{
  "share_link": "https://soundraw.io/edit_music?m=...",
  "variation_type": "customize",
  "energy_preset": "building",
  "mute_stems": ["me"]
}

Stem codes: bc (backing), bs (bass), dr (drums), me (melody), fe (fill end), ff (fill start)

3. adaptive_layer_control

Generate multiple versions with different stems muted for adaptive audio.

Input:

{
  "share_link": "https://soundraw.io/edit_music?m=...",
  "layers_to_keep": ["drums", "bass", "melody", "backing"]
}

Output: Separate audio URLs for each layer + JavaScript integration code for runtime mixing.

4. scene_transition_music

Generate transition music between scenes.

Input:

{
  "from_scene": "peaceful village exploration",
  "to_scene": "intense boss battle",
  "transition_type": "stinger",
  "duration_seconds": 15
}

Transition Types:

• fade: Gradual energy shift
• stinger: Dramatic accent
• crossfade: Smooth blend

Usage with Claude Code

Add to ~/.mcp.json:

{
  "mcpServers": {
    "soundraw-game-bgm": {
      "command": "node",
      "args": ["/path/to/soundraw-game-bgm/dist/index.js"],
      "env": {
        "DEEPSEEK_API_KEY": "sk-your-key",
        "SOUNDRAW_API_KEY": "your-bearer-token"
      }
    }
  }
}

Then restart Claude Code and try:

Generate epic boss battle music for my Dark Souls-like game, 60 seconds, with Unreal Engine integration code

Soundraw API Parameters

The server maps game scenes to these Soundraw parameters:

Moods: Angry, Busy & Frantic, Dark, Dreamy, Elegant, Epic, Euphoric, Fear, Funny & Weird, Glamorous, Happy, Heavy & Ponderous, Hopeful, Laid Back, Mysterious, Peaceful, Restless, Romantic, Running, Sad, Scary, Sentimental, Sexy, Smooth, Suspense

Genres: Acoustic, Hip Hop, Beats, Funk, Pop, Drum n Bass, Trap, Tokyo night pop, Rock, Latin, House, Tropical House, Ambient, Orchestra, Electro & Dance, Electronica, Techno & Trance, Jersey Club, Drill, R&B, Lofi Hip Hop, World, Afrobeats, Christmas

Themes: Ads & Trailers, Broadcasting, Cinematic, Corporate, Comedy, Cooking, Documentary, Drama, Fashion & Beauty, Gaming, Holiday Season, Horror & Thriller, Motivational & Inspiring, Nature, Photography, Sports & Action, Technology, Travel, Tutorials, Vlogs, Wedding & Romance, Workout & Wellness

Tempo: low (<100 bpm), normal (100-125 bpm), high (>125 bpm)

Energy Levels: Muted, Low, Medium, High, Very High

Development

# Run in development mode (watches for changes)
npm run dev

# Type check
npm run typecheck

# Build
npm run build

# Run built version
npm start

# Test API connections
npm run test:apis

Cost

Component	Purpose	Cost
DeepSeek	Scene analysis → Soundraw params	~$0.001/request
Soundraw	Music generation	Per your B2B plan

DeepSeek handles the reasoning at ~90% less cost than Claude API.

License

MIT