omr-mcp

MCP server that converts sheet music images to MusicXML using optical music recognition (OMR).

What it does

Takes a photo or scan of printed sheet music and returns a MusicXML document. Handles single pages or multi-page scores. Feeds directly into the rest of the choir-music-assistant pipeline.

Tools

Tool Description
recognize_sheet Convert a single image (file path or base64) to MusicXML string
recognize_sheet_to_file Convert a single image and write MusicXML to a file
recognize_sheets Process multiple pages and merge them into one MusicXML document
list_capabilities Return server metadata: backend version, input/output formats, available tools

Installation

cd omr-mcp
uv sync

On first run, oemer downloads ~100 MB of model checkpoints. This happens once and is cached.

Running

uv run omr-mcp

No environment variables required.

Claude Desktop configuration

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

Usage examples

// Recognize a single image file
{"tool": "recognize_sheet", "arguments": {"image_path": "/path/to/scan.png"}}

// Recognize from base64-encoded image
{"tool": "recognize_sheet", "arguments": {"image_base64": "<base64 data>", "mime_type": "image/jpeg"}}

// Process multiple pages into one score
{"tool": "recognize_sheets", "arguments": {"image_paths": ["/path/page1.png", "/path/page2.png"]}}

// Save result directly to file
{"tool": "recognize_sheet_to_file", "arguments": {"image_path": "/path/scan.png", "output_path": "/tmp/score.mxl"}}

Testing

# Unit tests (fast, no model required)
VIRTUAL_ENV= .venv/bin/pytest tests/ -v

# Integration tests (requires model download, ~10 min per page)
VIRTUAL_ENV= .venv/bin/pytest tests/ -v -m integration

Test samples

SATB a cappella samples are available in test_samples/pdmx_satb_samples/:

pdmx_satb_samples/
├── mxl/    # MusicXML ground truth
├── pdf/    # PDF scores
└── png/    # PNG images (OMR input)

Source: PDMX dataset — 250K+ public domain scores.

Dependencies

  • oemer — deep learning OMR engine (UNet + SVM, ONNX Runtime)
  • Pillow — image loading and validation
  • defusedxml — safe XML parsing
  • mcp — MCP protocol

Performance notes

  • Processing time: 3–5 minutes per page on CPU
  • oemer output may vary slightly between runs — do not assert on exact XML equality
  • The generated MusicXML is functionally correct but may not pass strict schema validation

System requirements

  • Python 3.11+
  • No system libraries required (ONNX Runtime is bundled via pip)

Project links

Data verified by PyPI on Aug 16, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for raulkivi from gravatar.com raulkivi

Credits

Author: Raul Kivi

GitHub Statistics

Data verified by PyPI on Aug 16, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.11

Provides Extra

dev

Tags

mcp music musicxml omr optical-music-recognition sheet-music

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

omr_mcp-0.1.2.tar.gz (142.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

omr_mcp-0.1.2-py3-none-any.whl (11.2 kB view details)

Uploaded Python 3

File details

Details for the file omr_mcp-0.1.2.tar.gz.

File metadata

  • Download URL: omr_mcp-0.1.2.tar.gz
  • Upload date:
  • Size: 142.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for omr_mcp-0.1.2.tar.gz
Algorithm Hash digest
SHA256 fc427f8b3a2a23e23411ee6e2a151bf1c1d8d5f8720a78fc881263247486d714
MD5 026de7f55a361112c690f3dade92953c
BLAKE2b-256 fe9c7c9a2086012685a73777d905dea8359c68881f757a7ad0b12a2c8a64c1aa

See more details on using hashes here.

Provenance

The following attestation bundles were made for omr_mcp-0.1.2.tar.gz:

Publisher: publish.yml on raulkivi/music-assistant

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file omr_mcp-0.1.2-py3-none-any.whl.

File metadata

  • Download URL: omr_mcp-0.1.2-py3-none-any.whl
  • Upload date:
  • Size: 11.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for omr_mcp-0.1.2-py3-none-any.whl
Algorithm Hash digest
SHA256 6798bd424dd4eb6c1b3d9eea6b11f8dae04105573a0f24b21d0503dfb5621c10
MD5 777e1f031988d1ea9fb5b5140c806b1f
BLAKE2b-256 e1c73804c916bfd23a3529b2ebaf8523b85b77b93380144e5f94b5752c58364d

See more details on using hashes here.

Provenance

The following attestation bundles were made for omr_mcp-0.1.2-py3-none-any.whl:

Publisher: publish.yml on raulkivi/music-assistant

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.2 This release

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page