music21

Music21 Analysis MCP Server exposes multiple interfaces to access the same core music21 analysis capabilities. The MCP server runs in Python and provides a protocol-independent backend that can be paired with Claude Desktop via MCP, or used directly through the HTTP API, the CLI, or the Python library. Start by launching the MCP server (music21_mcp.server_minimal) with the Python interface, then choose the interface that fits your workflow. The HTTP API offers REST endpoints for importing scores, running analyses (e.g., key or harmony), and exporting results, while the CLI provides automation-friendly commands for bulk processing. The Python library allows you to create a direct, programmatic analyzer and perform quick analyses or integrate the tools into larger workflows without network calls.

Prerequisites:

• Python 3.10+ installed on your system
• Git for cloning the repository or installing from PyPI
• Optional: uv (for UV-based environment) if you prefer that setup

Install from PyPI (recommended):

pip install music21-mcp-server

Run the MCP server (Python interface):

# Start MCP server (MCP interface)
python -m music21_mcp.launcher mcp

# Start HTTP API server (REST API)
python -m music21_mcp.launcher http

# Start CLI interface (interactive CLI)
python -m music21_mcp.launcher cli

If you prefer to run the server using UV for development or local testing (recommended for local devs):

# Install UV (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Run the server via UV (example for Python-based server)
uv run music21-mcp-server

Configuration for Claude Desktop (example) is shown in the README; adapt the command to your environment as needed:

# Example Claude Desktop configuration
{
  "mcpServers": {
    "music21-analysis": {
      "command": "python",
      "args": ["-m", "music21_mcp.server_minimal"],
      "env": {
        "PYTHONPATH": "/path/to/music21-mcp-server/src"
      }
    }
  }
}

Environment variables:

• MUSIC21_MCP_LOG_LEVEL (e.g., INFO) controls logging verbosity
• MUSIC21_MCP_CACHE_SIZE and MUSIC21_MCP_TIMEOUT tune internal caching and timeouts
• PYTHONPATH may need to include the project src path when integrating with specific editors or CLIs Common issues:
• Ensure Python 3.10+ is used and dependencies are installed (pip install music21-mcp-server or install from source)
• When using Claude Desktop integration, you may need to customize PYTHONPATH to point to the server module location
• If the HTTP API returns 404 or 500, verify that the correct interface (http) is running and the port (default 8000) is accessible

Configuration options:

• The MCP server exposes the following interfaces: mcp, http, cli, and the Python library (via adapters)
• Environment-based configuration allows you to point the server to a local music21 corpus setup or override default paths
• You can import/export scores in various formats (MusicXML, MIDI, ABC, Lilypond) and perform analyses like key, harmony, and voice-leading