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)
# Install the package
pip install music21-mcp-server
# Start the server
music21-mcp-server --mode mcp # For Claude Desktop
music21-mcp-server --mode http # REST API at localhost:8000
music21-mcp-server --mode cli # Interactive CLI
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 -r requirements.txt
# 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.adapters 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
# Reality-based test suite (95% core, 5% adapter)
python tests/run_reality_tests.py
# Core music21 tests (must pass)
python -m pytest tests/core/ -v
# MCP adapter tests (may fail - that's expected)
python -m pytest tests/adapters/ -v
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
- 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
# Optional configuration
export MUSIC21_MCP_LOG_LEVEL=INFO
export MUSIC21_MCP_CACHE_SIZE=100
export MUSIC21_MCP_TIMEOUT=30
Music21 Setup
# 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
# 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:
- π 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 >76% 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=76 - 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! π΅