Skip to main content
Glama

Music21 Analysis - Multi-Interface Music Server

CI/CD Pipeline CI Coverage Python 3.10+ License: MIT Ruff MCP

Professional music analysis with 4 different interfaces - MCP server, HTTP API, CLI tools, and Python library. Built on the powerful music21 library with protocol-independent architecture for maximum reliability.

๐ŸŽฏ Why Multiple Interfaces?

Based on 2025 research showing MCP has 40-50% production success rate, this project provides multiple pathways to the same powerful music21 analysis functionality:

  • ๐Ÿ“ก MCP Server - For Claude Desktop integration (when it works)

  • ๐ŸŒ HTTP API - For web applications (reliable backup)

  • ๐Ÿ’ป CLI Tools - For automation (always works)

  • ๐Ÿ Python Library - For direct programming access

Related MCP server: MusicBrainz MCP Server

๐ŸŽต Core Music Analysis Features

Analysis Tools (13 Available)

  • Import & Export: MusicXML, MIDI, ABC, Lilypond, music21 corpus

  • Key Analysis: Multiple algorithms (Krumhansl, Aarden, Bellman-Budge)

  • Harmony Analysis: Roman numerals, chord progressions, cadence detection

  • Voice Leading: Parallel motion detection, voice crossing analysis

  • Pattern Recognition: Melodic, rhythmic, and harmonic patterns

Advanced Capabilities

  • Harmonization: Bach chorale and jazz style harmonization

  • Counterpoint: Species counterpoint generation (1-5)

  • Style Imitation: Learn and generate music in composer styles

  • Score Manipulation: Transposition, time stretching, orchestration

๐Ÿš€ Quick Start

Installation

# Install the package
pip install music21-mcp-server

# Start the server
music21-mcp          # MCP server for Claude Desktop
music21-http         # REST API at localhost:8000
music21-cli          # Interactive CLI
music21-analysis mcp          # Unified launcher (positional arg)

Install from Source

# Clone repository
git clone https://github.com/brightlikethelight/music21-mcp-server.git
cd music21-mcp-server

# Install with UV (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Or with pip
pip install .

# Configure music21 corpus
python -m music21.configure

Usage - Pick Your Interface

๐ŸŽฏ Show All Available Interfaces

python -m music21_mcp.launcher

๐Ÿ“ก MCP Server (for Claude Desktop)

# Start MCP server
python -m music21_mcp.launcher mcp

# Configure Claude Desktop with:
# ~/.config/claude-desktop/config.json
{
  "mcpServers": {
    "music21-analysis": {
      "command": "python",
      "args": ["-m", "music21_mcp.server_minimal"],
      "env": {
        "PYTHONPATH": "/path/to/music21-mcp-server/src"
      }
    }
  }
}

๐ŸŒ HTTP API Server (for web apps)

# Start HTTP API server
python -m music21_mcp.launcher http
# Opens: http://localhost:8000
# API docs: http://localhost:8000/docs

# Example usage:
curl -X POST "http://localhost:8000/scores/import" \
  -H "Content-Type: application/json" \
  -d '{"score_id": "chorale", "source": "bach/bwv66.6", "source_type": "corpus"}'

curl -X POST "http://localhost:8000/analysis/key" \
  -H "Content-Type: application/json" \
  -d '{"score_id": "chorale"}'

๐Ÿ’ป CLI Tools (for automation)

# Show CLI status
python -m music21_mcp.launcher cli status

# Import and analyze a Bach chorale
python -m music21_mcp.launcher cli import chorale bach/bwv66.6 corpus
python -m music21_mcp.launcher cli key-analysis chorale
python -m music21_mcp.launcher cli harmony chorale roman

# List all tools
python -m music21_mcp.launcher cli tools

๐Ÿ Python Library (for programming)

from music21_mcp import create_sync_analyzer

# Create analyzer
analyzer = create_sync_analyzer()

# Import and analyze
analyzer.import_score("chorale", "bach/bwv66.6", "corpus")
key_result = analyzer.analyze_key("chorale")
harmony_result = analyzer.analyze_harmony("chorale", "roman")

print(f"Key: {key_result}")
print(f"Harmony: {harmony_result}")

# Quick comprehensive analysis
analysis = analyzer.quick_analysis("chorale")

๐Ÿงช Testing & Development

Run Tests

# Run all tests
python -m pytest tests/ -v

# Run with coverage threshold
python -m pytest tests/ --cov=src/music21_mcp --cov-fail-under=82

Development Setup

# Install development dependencies
uv sync --dev

# Set up pre-commit hooks
pre-commit install

# Run linting
ruff check src/
ruff format src/

# Type checking
mypy src/

๐Ÿ—๏ธ Architecture

Protocol-Independent Design

Core Value Layer:
โ”œโ”€โ”€ services.py              # Music21 analysis service (protocol-independent)
โ””โ”€โ”€ tools/                   # 13 music analysis tools

Protocol Adapter Layer:
โ”œโ”€โ”€ adapters/mcp_adapter.py   # MCP protocol isolation
โ”œโ”€โ”€ adapters/http_adapter.py  # HTTP/REST API
โ”œโ”€โ”€ adapters/cli_adapter.py   # Command-line interface  
โ””โ”€โ”€ adapters/python_adapter.py # Direct Python access

Unified Entry Point:
โ””โ”€โ”€ launcher.py              # Single entry point for all interfaces

Design Philosophy

  • Core Value First: Music21 analysis isolated from protocol concerns

  • Protocol Apocalypse Survival: Works even when MCP fails (30-40% of time)

  • Multiple Escape Hatches: Always have a working interface

  • Reality-Based: Built for today's MCP ecosystem, not enterprise dreams

๐Ÿ“Š Interface Reliability

Interface

Success Rate

Best For

MCP

40-50%

AI assistant integration

HTTP

95%+

Web applications

CLI

99%+

Automation & scripting

Python

99%+

Direct programming

๐Ÿ“š Documentation

Discord Webhook Integration

๐Ÿ”ง Configuration

Environment Variables

# Server host and port (used by HTTP adapter and launcher)
export MUSIC21_MCP_HOST=127.0.0.1
export MUSIC21_MCP_PORT=8000

# Operation timeouts (seconds)
export MUSIC21_MCP_TIMEOUT=30          # General async operation timeout
export MUSIC21_TOOL_TIMEOUT=30         # Per-tool execution timeout
export MUSIC21_CHORD_ANALYSIS_TIMEOUT=60  # Chord analysis timeout
export MUSIC21_BATCH_TIMEOUT=30        # Batch processing timeout

# CORS origins for HTTP adapter (comma-separated)
export MUSIC21_CORS_ORIGINS="http://localhost:*"

Music21 Setup

# Configure corpus path (one-time setup)
python -m music21.configure

๐Ÿ› ๏ธ Available Analysis Tools

  1. import_score - Import from corpus, files, URLs

  2. list_scores - List all imported scores

  3. get_score_info - Detailed score information

  4. export_score - Export to MIDI, MusicXML, etc.

  5. delete_score - Remove scores from storage

  6. analyze_key - Key signature analysis

  7. analyze_chords - Chord progression analysis

  8. analyze_harmony - Roman numeral/functional harmony

  9. analyze_voice_leading - Voice leading quality analysis

  10. recognize_patterns - Melodic/rhythmic patterns

  11. harmonize_melody - Automatic harmonization

  12. generate_counterpoint - Counterpoint generation

  13. imitate_style - Style imitation and generation

๐Ÿš€ Quick Examples

Analyze a Bach Chorale

# CLI approach
python -m music21_mcp.launcher cli import chorale bach/bwv66.6 corpus
python -m music21_mcp.launcher cli key-analysis chorale

# Python approach  
analyzer = create_sync_analyzer()
analyzer.import_score("chorale", "bach/bwv66.6", "corpus")
print(analyzer.analyze_key("chorale"))

Start Services

# For Claude Desktop
python -m music21_mcp.launcher mcp

# For web development
python -m music21_mcp.launcher http

# For command-line work
python -m music21_mcp.launcher cli status

๐Ÿ”„ Migration from v1.0

The previous enterprise version has been simplified for reliability:

  • โœ… Kept: All music21 analysis functionality

  • โœ… Added: HTTP API, CLI, Python library interfaces

  • โŒ Removed: Docker, K8s, complex auth, monitoring (too unstable for MCP ecosystem)

  • ๐Ÿ”„ Changed: Focus on core value delivery through multiple interfaces

๐Ÿ”” Discord Webhook Integration

Get real-time notifications for CI/CD pipeline status, pull requests, and releases:

๐Ÿค Contributing

We welcome contributions! Please see our Contributing Guide for details on:

  • Development setup and requirements

  • Code style guidelines (Ruff, MyPy)

  • Testing requirements (maintain >82% coverage)

  • Pull request process

  • Branch protection rules

Quick start:

  1. Fork the repository

  2. Create feature branch: git checkout -b feature/amazing-feature

  3. Run tests: pytest tests/ --cov=src/music21_mcp --cov-fail-under=82

  4. Commit changes: git commit -m 'feat: Add amazing feature'

  5. Push branch: git push origin feature/amazing-feature

  6. Submit pull request

๐Ÿ“„ License

MIT License - see LICENSE file for details.

๐Ÿ™ Acknowledgments

  • Built on the excellent music21 library

  • Uses FastMCP for MCP protocol support

  • Inspired by the need for reliable music analysis tools


Choose the interface that works for you. All provide the same powerful music21 analysis capabilities! ๐ŸŽต

Available Tools

14 tools
chord_analysisC

Analyze chord progressions in a score

Inputs: score_id (required).

delete_scoreC

Delete a score from storage

Inputs: score_id (required).

export_scoreD

Export a score to various formats

Inputs: score_id (required), format.

generate_counterpointC

Generate species counterpoint (1=note-against-note, 2=2:1, 3=3:1, 4=syncopated, 5=florid)

Inputs: score_id (required), species, voice_position.

harmonize_melodyC

Generate harmonization for a melody in various styles (classical, jazz, pop, modal)

Inputs: score_id (required), style, voice_parts.

harmony_analysisC

Perform harmony analysis (roman numeral or functional)

Inputs: score_id (required), analysis_type.

health_checkB

Check server and adapter health

Inputs: no named parameters.

imitate_styleB

Generate music imitating a specific composer style (bach, mozart, chopin, debussy) or analyze score for style

Inputs: composer, score_id, complexity, generation_length.

import_scoreC

Import a score from various sources

Inputs: source (required), score_id (required), source_type.

key_analysisC

Analyze the key signature of a score

Inputs: score_id (required).

list_scoresC

List all available scores

Inputs: no named parameters.

pattern_recognitionD

Recognize patterns in music

Inputs: score_id (required), pattern_type.

score_infoC

Get detailed information about a score

Inputs: score_id (required).

voice_leading_analysisC

Analyze voice leading patterns in a score

Inputs: score_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    C2.8/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct task: analysis tools (chord, harmony, key, voice leading, pattern) are clearly separated, generation tools (counterpoint, harmonization, style imitation) are unique, and file management (import/export/list/delete/info) plus health check round out the set without overlap.

    Naming Consistency4/5

    All names use lowercase with underscores, but there is a mix of verb-noun (e.g., delete_score, generate_counterpoint) and noun-verb/noun-noun patterns (e.g., chord_analysis, health_check). The inconsistency is minor and the names remain clear and predictable.

    Tool Count5/5

    14 tools cover analysis, generation, and file management without being excessive. The count is well-scoped for a music theory server, each tool earns its place.

    Completeness4/5

    The set covers core music analysis and generation tasks, plus basic score I/O. Missing a 'create_score' tool (relying on import/generation) and some advanced compositional features, but overall it's reasonably complete for its domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A composition-focused server built on music21 for generative music workflows, enabling melody generation, musical transformations, chord reharmonization, counterpoint creation, and MIDI export through constraint-based algorithmic composition tools.
      1
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      MCP server for vibe coding with music, enabling format conversion (LilyPond, MusicXML, MIDI, ABC, etc.), audio-to-sheet transcription, and transposition with robust fallback outputs.
      1
      -