musescore-mcp

MCP server for MuseScore — search sheet music and read score metadata from Claude. MuseScore has no public API and sits behind Cloudflare, so every request rides your signed-in musescore.com browser tab via the fetchproxy extension — Cloudflare sees a real browser session, not a Node process.

Private, personal-use server (not published to any registry). Developed and maintained by AI (Claude). Use at your own discretion.

Tools

| Tool | What it does | | --- | --- | | musescore_search | Search scores. Defaults to the "Free to view, play & download" facet (free_only=true). Returns id, title, uploader, composer, instrumentation, difficulty, page/part counts, view/save/download counts, and downloadability flags. | | musescore_get_score | One score's metadata — title, license, measures, key, parts, duration, upload/update dates — by URL or user_id + score_id. | | musescore_download | Resolve the official download URL (pdf/mid/mscz/mxl) for a free or entitled score, from the store's type_download_list. Read-only: returns the link to open in your browser (the MCP can't stream the file — see Downloads). | | musescore_score_to_pdf | Create a PDF for a score at output_path. Downloads the official PDF bytes when MuseScore exposes one; otherwise fetches the page SVG and stitches it into a PDF (pure JS — no system deps). | | musescore_healthcheck | Round-trip a public MuseScore URL through the fetchproxy bridge and report which hop failed. | | musescore_register_session / _set_active_session / _get_session_context | Session registry bookkeeping. | | musescore_svg_to_pdf | Convert local .svg / .svgz files that already exist on disk into a PDF, one file per page. Pure JS (pdfkit + svg-to-pdfkit) — no system dependencies. |

How it works

The server-rendered HTML has no result cards — MuseScore hydrates them client-side from an entity-encoded JSON store embedded in the page (its analogue of Next.js __NEXT_DATA__). The parsers recover that JSON and read the score objects directly. See docs/MUSESCORE-API.md.

Downloads

Download links live in the store's type_download_list ({type, url} for pdf / mid / mscz / mxl / mp3 …). Free scores (is_free) download fine — and they almost all report hasAccess: false, which is an entitlement flag (purchased / PRO), not the free-download signal. So the gate is is_free === true or hasAccess === true; paid scores you haven't bought are refused.

musescore_download is a resolver, not a fetcher: the download endpoint is Cloudflare-walled and 302-redirects cross-origin to presigned S3, which only a browser navigation can follow — neither a server-side fetch nor the fetchproxy bridge can. So the tool returns the official download_url (gated to free/entitled scores) for you to open in your signed-in browser; it never streams or writes the file, and never scrapes the page tiles. Full verified mechanism: docs/MUSESCORE-API.md.

Use musescore_score_to_pdf when you want the best available PDF path for a score. If MuseScore exposes a full pdf entry, the tool downloads the official PDF bytes to output_path (the same capture-redirect → presigned-S3 byte path musescore_download uses). If no full pdf format is present, it falls back to fetching the page SVG (/static/musescore/scoredata/g/<hash>/score_<n>.svg) and stitching it into output_path with pdfkit + svg-to-pdfkit (pure JS, no external binary). The hash is extracted from the h= parameter of a pdf or pdf-sample download URL.

Setup

1. Install the fetchproxy extension and open musescore.com signed in, with the Cloudflare check cleared.

2. Point your MCP host at the built bundle:

   {
     "mcpServers": {
       "musescore": {
         "command": "node",
         "args": ["/absolute/path/to/musescore-mcp/dist/bundle.js"]
       }
     }
   }

Development

npm install
npm run build      # tsc --noEmit + esbuild → dist/bundle.js
npm test           # vitest, mocked client, no network

No env vars required. Optional: MUSESCORE_WS_PORT (default 37149), MUSESCORE_DEBUG=1.

SVG→PDF conversion is pure JavaScript (pdfkit + svg-to-pdfkit) — no system binary or native dependency to install.

License

MIT