encoding-music-mcp

MCP server for analyzing MEI (Music Encoding Initiative) files. Provides tools to extract metadata, analyze musical structure, and understand encoded scores.

Features

• 46 Built-in MEI Files: Bach Inventions, Bartók Mikrokosmos, Morley Canzonets - ready to analyze
• MEI Metadata Extraction: Extract title, composer, editors, analysts, publication dates, and copyright information
• Key Analysis: Detect musical keys with confidence scores using music21
• Interval Analysis: Extract notes, melodic intervals, harmonic intervals, and melodic n-grams using CRIM Intervals
• Notation Display: Render sheet music as SVG with interactive pagination using Verovio (requires MCP Apps extension)
• Simple & Efficient: Tools read directly from disk - no token waste

Documentation

📚 Read the full documentation for:

• Detailed tool reference
• Quick start guides
• MEI file collection details
• Development guides
• API reference

Installation

Prerequisites: This project requires uv to be installed.

Option 1: Quick Start (using uvx)

No cloning required! Add this to your MCP client configuration:

{
  "mcpServers": {
    "encoding-music-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/unimelbmdap/encoding-music-mcp.git",
        "encoding-music-mcp"
      ]
    }
  }
}

Option 2: Local Development

Clone the repository and install dependencies:

git clone https://github.com/unimelbmdap/encoding-music-mcp.git
cd encoding-music-mcp
uv sync

Usage

With Claude Desktop

1. Open your Claude Desktop configuration file:

   • In Claude Desktop, open Settings > Developer
   • Under Local MCP servers, click Edit Config

2. Add configuration (choose one method):

Method A: Using uvx (no clone needed)

{
  "mcpServers": {
    "encoding-music-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/unimelbmdap/encoding-music-mcp.git",
        "encoding-music-mcp"
      ]
    }
  }
}

Method B: Using local clone

{
  "mcpServers": {
    "encoding-music-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/encoding-music-mcp",
        "run",
        "encoding-music-mcp"
      ]
    }
  }
}

[!NOTE] Replace /absolute/path/to/encoding-music-mcp with the full path to your cloned repository.

On Windows, an absolute path is formatted using \\ in place of /.

For example: C:\\absolute\\path\\to\\encoding-music-mcp

3. Restart Claude Desktop

4. Try it out:

   • “What MEI files are available?” → Lists all 46 built-in files
   • “Tell me about Bach_BWV_0772.mei” → Extracts metadata
   • “What key is Bach_BWV_0772.mei in?” → Analyzes key with confidence score
   • “Get the melodic intervals for Bach_BWV_0772.mei” → Extracts melodic intervals
   • “Find melodic 4-grams in Bach_BWV_0772.mei” → Extracts melodic n-grams
   • “Show me the notation for Bach_BWV_0772.mei” → Displays rendered sheet music

Standalone

Run the server directly:

uv run encoding-music-mcp

Available Tools

list_available_mei_files

Discover all built-in MEI files.

Returns: Dictionary with:

• bach_inventions: List of Bach files
• bartok_mikrokosmos: List of Bartók files
• morley_canzonets: List of Morley files
• all_files: Complete list of all filenames

get_mei_metadata

Extract detailed metadata from a built-in MEI file.

Parameters:

• filename (string, required): Name of the MEI file (e.g., “Bach_BWV_0772.mei”)

Returns: Dictionary with metadata including:

• Title and work title
• Composer
• MEI editors
• XML editors
• Analysts
• Publication date
• Copyright/availability information
• Application used to create the file

Example output:

{
  "title": "Invention No. 1 in C major",
  "composer": "Bach, Johann Sebastian",
  "mei_editors": ["Freedman, Richard"],
  "xml_editors": ["Schölkopf, Tobias"],
  "analysts": ["Student, This"],
  "publication_date": "2024-11-19"
}

analyze_key

Analyze the musical key of a piece using music21’s key detection algorithm.

Parameters:

• filename (string, required): Name of the MEI file (e.g., “Bach_BWV_0772.mei”)

Returns: Dictionary with:

• Key Name: The detected key (e.g., “C major”, “a minor”)
• Confidence Factor: Correlation coefficient between 0.0 and 1.0

Example output:

{
  "Key Name": "C major",
  "Confidence Factor": 0.9451
}

get_notes

Extract all notes from an MEI file using CRIM Intervals.

Parameters:

• filename (string, required): Name of the MEI file (e.g., “Bach_BWV_0772.mei”)

Returns: Dictionary with:

• filename: The input filename
• notes: String representation of the notes dataframe with pitch and octave information

Columns represent individual staves or voice parts. Rows represent measure and beat information as floats.

get_melodic_intervals

Extract melodic intervals from an MEI file using CRIM Intervals.

Parameters:

• filename (string, required): Name of the MEI file (e.g., “Bach_BWV_0772.mei”)

Returns: Dictionary with:

• filename: The input filename
• melodic_intervals: String representation of the melodic intervals dataframe

Columns represent individual staves or voice parts. Rows represent measure and beat information as floats.

get_harmonic_intervals

Extract harmonic intervals from an MEI file using CRIM Intervals.

Parameters:

• filename (string, required): Name of the MEI file (e.g., “Bach_BWV_0772.mei”)

Returns: Dictionary with:

• filename: The input filename
• harmonic_intervals: String representation of the harmonic intervals dataframe

Columns represent pairs of voice parts. Rows represent measure and beat information as floats.

get_melodic_ngrams

Extract melodic n-grams from an MEI file using CRIM Intervals.

Parameters:

• filename (string, required): Name of the MEI file (e.g., “Bach_BWV_0772.mei”)
• n (integer, optional): Length of the n-grams (default: 4)

Returns: Dictionary with:

• filename: The input filename
• n: The n-gram length used
• melodic_ngrams: String representation of melodic n-grams dataframe

N-grams are tuples of intervals converted to strings with underscore separators (e.g., “2_-2_3_-1”).

show_notation

Display musical notation for an MEI file as rendered SVG. Requires the MCP Apps extension for inline display.

Parameters:

• filename (string, required): Name of the MEI file (e.g., “Bach_BWV_0772.mei”)
• start_measure (integer, optional): First measure to display (defaults to full piece)
• end_measure (integer, optional): Last measure to display (defaults to start_measure if only start given)
• page (integer, optional): Page number to display (default: 1)

Returns: SVG notation rendered by Verovio, displayed in an interactive viewer with pagination controls.

For example:

Built-in Files

The server includes 46 MEI files:

• 15 Bach Two-Part Inventions (BWV 772-786)
• 19 Bartók Mikrokosmos pieces
• 12 Morley Canzonets from 1595

Use list_available_mei_files() to discover all available files.

Development

The project uses uv for dependency management:

# Install dependencies
uv sync

# Run the server
uv run encoding-music-mcp

# Format code
uv run ruff format .

# Run tests
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Serve documentation locally
uv run mkdocs serve

# Build documentation
uv run mkdocs build

Testing

The project includes comprehensive tests for all tools. See tests/README.md for detailed testing documentation.

Documentation

Documentation is built with MkDocs Material:

# Serve locally at http://localhost:8000
uv run mkdocs serve

# Build static site
uv run mkdocs build

Coming Soon

Additional tools planned:

• Time signature detection
• Pitch histograms and frequency analysis
• Lyrics extraction
• Pattern matching and similarity detection

License

MIT