Music Forge

English | Русский

A scalable MCP plugin/service for downloading and processing audio: SoundCloud (starting point), then YouTube/Yandex Music/Spotify; transcoding, tagging and cover art embedding, HTTP API, MCP tools, audio workers.

Quickstart

Variant A: Docker Compose (recommended)

cp .env.example .env
make upb       # build and start the stack

Endpoints:

• API: http://localhost:8033
• Admin: http://localhost:8033/admin
• MCP HTTP: http://localhost:8033/mcp

Management:

make logs      # logs
make ps        # container status
make up        # just up
make down      # stop and remove

Variant B: Local (uv)

make install   # create .venv, install deps, copy .env
source .venv/bin/activate

make lint      # ruff + black + mypy
make test      # mypy + pytest

# run API
uvicorn api.main:app --reload

# MCP (stdio)
python -m mcp_music_forge.mcp_app

API Examples

# health check
curl -s http://localhost:8033/health | jq
# {"status": "ok"}

# enqueue download (SoundCloud URL with allowed download per ToU)
curl -s -X POST 'http://localhost:8033/download?url=https://soundcloud.com/artist/track' | jq
# {"job_id": "abc123", "status": "queued"}

# check job status
curl -s http://localhost:8033/jobs/<job_id> | jq

MCP Tools

• probe_url: provider detection and downloadability check.
• enqueue_download: create/duplicate a job, put it in the queue.
• get_job_status: status, artifacts, file links as MCP resources.
• Resources: forge://jobs/<job_id>/{original|final}/<filename> (file bytes).

Project Overview

• MCP Server (mcp_music_forge/): job management, resource provider, and MCP tools.
• HTTP API (api/): POST /download, GET /jobs/{id}, /health, admin interface.
• Providers (providers/): adapters for sources (starting with SoundCloud).
• Transcoder (transcoder/): a wrapper around ffmpeg.
• Storage (storage/): local FS (can be replaced with S3, etc.).
• Queue (core/services/queue.py): ARQ + Redis; a wrapper in workers/.

Documentation

• Build / Run / Deploy
• Architecture
• CI/CD

Legal Notes

• SoundCloud provider respects ToU: we only download if the track is downloadable (downloadable/download_url).
• Cookie file support is available, but use it strictly within the service's rules.