Music Genre MCP

An offline-first Model Context Protocol server for resolving music genres and building deterministic prompts for music-generation models.

It prevents a common failure mode in agentic music systems: an unknown or misspelled genre silently falling back to a generic prompt such as 120 BPM, A minor. Music Genre MCP resolves canonical names and aliases, tracks provenance, and fails closed when a generator profile is unavailable.

Features

• 2,201 canonical MusicBrainz genres and MBIDs in the included snapshot.

• Conservative Wikidata aliases and explicitly sourced genre relationships.

• Separate known and generation_ready states.

• Deterministic YuE2-oriented style prompts and explicit genre mixing.

• SQLite runtime with no network access.

• Provenance, confidence, evidence, relations, and empirical-tempo schema.

• No generic BPM, key, or genre fallback for unknown input.

Related MCP server: Author Style "-esque" MCP Server

Installation

Python 3.11 or newer is required.

git clone https://github.com/plohoy/music-genre-mcp.git
cd music-genre-mcp
python3 -m venv .venv
./.venv/bin/pip install -e .

The repository includes a ready SQLite database and reproducible source snapshots. To rebuild and reimport them without refreshing the network data:

python scripts/build_db.py
python scripts/import_musicbrainz.py
python scripts/import_wikidata.py
python scripts/validate_db.py

Add --refresh to an importer only when you intentionally want a fresh remote snapshot.

MCP configuration

Generic stdio configuration:

{
  "mcpServers": {
    "music-genres": {
      "command": "/absolute/path/music-genre-mcp/.venv/bin/music-genres-mcp",
      "env": {
        "MUSIC_GENRES_DB": "/absolute/path/music-genre-mcp/data/music_genres.db"
      }
    }
  }
}

Hermes config.yaml:

mcp_servers:
  music-genres:
    command: /absolute/path/music-genre-mcp/.venv/bin/music-genres-mcp
    env:
      MUSIC_GENRES_DB: /absolute/path/music-genre-mcp/data/music_genres.db
    enabled: true
    timeout: 30

Test the connection:

hermes mcp test music-genres

MCP tools

Unknown input returns status: not_found. Every canonical genre shipped in the catalogue has a precompiled generator profile; runtime lookups never perform network enrichment and never pause to build a profile.

Command-line usage

music-genres get "trip-hop"
music-genres search "industrial techno"
music-genres prompt "industrial techno"
music-genres prompt idm ambient

Example prompt for industrial techno:

industrial techno, dark industrial techno, relentless four-on-the-floor kick,
distorted warehouse percussion, metallic impacts, grinding bass, cold machine
drones, atonal analog stabs, hypnotic functional arrangement, raw underground
production, no trance melody, no EDM buildup, no trap, no dubstep, 138 BPM,
F minor

Integration with music-generation models

Recommended agent contract

1. Extract only genre names explicitly supplied by the user.

2. Call build_generator_style_prompt.

3. Stop on not_found; show suggestions.

4. Pass the returned prompt directly to the generator.

5. Apply explicit user BPM/key through native backend fields when available.

6. Never append an LLM-written reinterpretation after the resolved prompt; it can overpower the intended genre.

For approved local profiles, the prompt builder also supplies generator-facing rhythm, bass, instrumentation, melodic language, arrangement, production, tempo, key and neighbouring-genre exclusions. Weighted blends retain the requested proportions, use their weighted-average BPM, and inherit the key of the dominant component. This completion happens only after successful genre resolution; unknown genres never receive a generic fallback profile.

YuE2

import subprocess
from music_genres.repository import build_style_prompt

profile = build_style_prompt(["industrial techno"])
if profile["status"] != "ok":
    raise ValueError(profile)

subprocess.run([
    "python", "generate.py",
    "--model", "8bit",
    "--style", profile["prompt"],
    "--lyrics", "[Instrumental]",
    "--cot", "full",
    "--max-semantic-tokens", "1500",
    "--out", "industrial-techno.wav",
], check=True)

YuE2 treats textual BPM, key, and genre descriptors as conditioning rather than hard constraints. With --cot full, its generated ABC plan may override tempo or harmony. For strict musical structure, provide a reviewed external ABC file or use a reference-audio workflow.

MiniMax Music

from music_genres.repository import build_style_prompt

profile = build_style_prompt(["trip-hop"])
style_prompt = profile["prompt"]

# Send style_prompt as the model's style/caption field.
# Send lyrics separately. For an instrumental request, use the backend's
# native instrumental/no-vocals control rather than relying only on prose.

Duration, instrumental mode, BPM, and key should remain separate API fields whenever the backend exposes them.

Generic HTTP generator

import requests
from music_genres.repository import build_style_prompt

profile = build_style_prompt(["neurofunk drum and bass"])
if profile["status"] == "ok":
    response = requests.post(
        "http://127.0.0.1:9000/generate",
        json={
            "style": profile["prompt"],
            "instrumental": True,
            "duration_seconds": 60,
        },
        timeout=1800,
    )
    response.raise_for_status()

Explicit genre blends

profile = build_style_prompt(["idm", "ambient"], weights=[0.6, 0.4])

The MCP adds no third genre. Weighted blends use their weighted-average BPM and inherit the key of the dominant requested component.

Data and provenance

The SQLite schema contains genres, aliases, relations, descriptors, generator profiles, tempo distributions, sources, and evidence. Generator BPM/key values are labelled heuristic and are not presented as empirical musicological truth.

Primary sources:

• MusicBrainz: canonical vocabulary and identifiers; core data is CC0.

• Wikidata: aliases, identifiers, and explicit graph claims; structured data is CC0.

• AcousticBrainz: planned empirical distributions after recording-to-genre coverage validation.

• FMA: planned hierarchy and feature cross-validation.

See artifacts/ for source, licence, feasibility, and method reports.

Development

./.venv/bin/pip install -e '.[dev]'
pytest
ruff check src tests scripts
python scripts/validate_db.py

The runtime server never contacts external services. Network access is needed only when refreshing build-time snapshots.

Precompiled generator profiles

The checked-in catalogue is fully precompiled: all canonical genres receive a generator profile before release. Curated/evidence-backed profiles are preserved; remaining entries are compiled deterministically from ordered musical-family archetypes, compound-genre matching and lexical modifiers. Profiles that cannot be classified beyond their canonical label are explicitly marked label-only rather than presented as researched musicology.

Inspect demand and status without network access:

music-genres profile-requests --limit 20
music-genres profile-status jazz

Refresh the complete precompiled catalogue after importing a new vocabulary:

python scripts/compile_all_profiles.py        # preview coverage
python scripts/compile_all_profiles.py --apply
python scripts/validate_db.py

An administrator can still replace a low-confidence profile with sourced enrichment:

python scripts/enrich_profile.py jazz --review-only
python scripts/enrich_profile.py jazz
python scripts/enrich_pending.py --limit 10

Optional enrichment resolves an exact Wikidata entity, retrieves its English Wikipedia article as attributed evidence, and extracts only descriptors from the checked-in controlled vocabulary. A candidate is promoted only when validation finds at least three supported descriptors spanning at least two categories. Explicit BPM ranges are preserved; BPM, key, and scale remain unset when the evidence does not state them. Ambiguous or thin evidence is stored as needs_review.

The MCP exposes get_generator_profile_status for provenance inspection. Network enrichment is deliberately excluded from the runtime MCP surface so an ordinary model call cannot mutate the genre knowledge base from arbitrary web content.

License

Project code is MIT licensed. Imported data keeps its original licence and provenance; see docs/SOURCES.md and artifacts/stage-0/licenses.md.