Music21 Analysis - Multi-Interface Music Server

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

🎵 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 from PyPI (Recommended)

hljs language-bash

# 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

hljs language-bash

# 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

hljs language-bash

python -m music21_mcp.launcher

📡 MCP Server (for Claude Desktop)

hljs language-bash

# 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)

hljs language-bash

# 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)

hljs language-bash

# 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)

hljs language-python

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

hljs language-bash

# 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

hljs language-bash

# 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

hljs language-bash

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

docs/architecture.md - System architecture overview
docs/getting-started.md - Quick start guide
examples/ - Working code examples
API Docs: http://localhost:8000/docs (when HTTP server running)

Discord Webhook Integration

.github/webhook-config.md - Complete Discord webhook setup guide
docs/webhook-integration.md - Advanced webhook configuration
scripts/test-webhook.sh - Test webhook connectivity
scripts/setup-webhook.sh - Automated webhook setup

🔧 Configuration

Environment Variables

hljs language-bash

# 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

hljs language-bash

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

🛠️ Available Analysis Tools

import_score - Import from corpus, files, URLs
list_scores - List all imported scores
get_score_info - Detailed score information
export_score - Export to MIDI, MusicXML, etc.
delete_score - Remove scores from storage
analyze_key - Key signature analysis
analyze_chords - Chord progression analysis
analyze_harmony - Roman numeral/functional harmony
analyze_voice_leading - Voice leading quality analysis
recognize_patterns - Melodic/rhythmic patterns
harmonize_melody - Automatic harmonization
generate_counterpoint - Counterpoint generation
imitate_style - Style imitation and generation

🚀 Quick Examples

Analyze a Bach Chorale

hljs language-bash

# 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

hljs language-bash

# 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:

📖 Webhook Setup Guide
🛠️ Quick Setup Script
🧪 Test Your Webhook
📚 Advanced Configuration

🤝 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:

Fork the repository
Create feature branch: git checkout -b feature/amazing-feature
Run tests: pytest tests/ --cov=src/music21_mcp --cov-fail-under=82
Commit changes: git commit -m 'feat: Add amazing feature'
Push branch: git push origin feature/amazing-feature
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! 🎵

music21-mcp-server

Music21 Analysis - Multi-Interface Music Server

🎯 Why Multiple Interfaces?

🎵 Core Music Analysis Features

Analysis Tools (13 Available)

Advanced Capabilities

🚀 Quick Start

Installation

Install from PyPI (Recommended)

Install from Source

Usage - Pick Your Interface

🎯 Show All Available Interfaces

📡 MCP Server (for Claude Desktop)

🌐 HTTP API Server (for web apps)

💻 CLI Tools (for automation)

🐍 Python Library (for programming)

🧪 Testing & Development

Run Tests

Development Setup

🏗️ Architecture

Protocol-Independent Design

Design Philosophy

📊 Interface Reliability

📚 Documentation

Discord Webhook Integration

🔧 Configuration

Environment Variables

Music21 Setup

🛠️ Available Analysis Tools

🚀 Quick Examples

Analyze a Bach Chorale

Start Services

🔄 Migration from v1.0

🔔 Discord Webhook Integration

🤝 Contributing

📄 License

🙏 Acknowledgments

Similar Packages

Repository

Tags

Original Author

Publisher