Mr. Magic MCP Server

Mr. Magic bridges LRCLIB, Genius, Musixmatch, and Melon so MCP clients, JSON HTTP automations, and CLI aficionados can all request lyrics from a single toolchain.

Table of Contents

• Prerequisites

• Installation

• Environment Variables

• Provider Credentials

• Export and Download Configuration

• Local Deployment

• Remote Deployment

• HTTP Endpoints

• MCP Tools

• Airtable Integration

• MCP Client Configuration

• CLI

• Manual Testing

• Provider Notes

• Changelog

• License

Related MCP server: Tempo

Prerequisites

• Node.js 18.17 or newer

• npm 9+

• macOS / Linux / WSL

• Provider credentials (see Provider Credentials)

Installation

Mr. Magic publishes four named binaries through npm:

Choose the option that matches how you'll use Mr. Magic.

Option 1 — Local clone (recommended for persistent use)

Cloning the repo is the simplest setup for local MCP clients (Cline, Claude Desktop, etc.) and for anyone who wants to use all features without extra ceremony. Credentials live in a local .env file — no need to inject every variable through an MCP client config. Token fetch scripts, the Playwright workflow, and local export storage all work out of the box.

1. Clone and install:

   git clone https://github.com/mrnajiboy/mr-magic-mcp-server.git
   cd mr-magic-mcp-server
   npm install

2. Create a .env file (copy .env.example as a starting point) and fill in your credentials. See Environment Variables for the full list.

3. Run the desired entrypoint:

   What you want	Command
   MCP stdio (local MCP clients)	node src/bin/mcp-server.js
   MCP Streamable HTTP & SSE (remote)	node src/bin/mcp-http-server.js
   JSON HTTP automation	node src/bin/http-server.js
   CLI	node src/bin/cli.js --help

   Or use the npm scripts:

   npm run server:mcp        # MCP stdio
   npm run server:mcp:http   # MCP Streamable HTTP & SSE — 127.0.0.1:3444
   npm run server:http       # JSON HTTP — 127.0.0.1:3333
   npm run cli -- --help     # CLI

   ⚠️ Stdio MCP clients: Do not use npm run server:mcp in your MCP client config. Use node src/bin/mcp-server.js directly. The npm script preamble is written to stdout before Node starts and causes "Unexpected token '>'" JSON-RPC errors on every connection.

See MCP Client Configuration → Local repo for the client config snippets.

Option 2 — npx (no clone, ephemeral or CI use)

npx is useful for quick one-off runs or CI contexts, but has an important limitation: the spawned process cannot read a local .env file — every credential must be passed as an environment variable in the shell or in your MCP client's env block.

This package publishes multiple binaries, so you must always specify which one you want using --package and then the binary name. npx -y mr-magic-mcp-server is not valid for this package — it would error because no binary named mr-magic-mcp-server exists.

MCP stdio server (for MCP client config)

# Shell (test only — real credentials come from MCP client env block)
MR_MAGIC_QUIET_STDIO=1 \
GENIUS_CLIENT_ID=your_id \
GENIUS_CLIENT_SECRET=your_secret \
MUSIXMATCH_DIRECT_TOKEN='...' \
  npx -y --package mr-magic-mcp-server mcp-server

For MCP clients (Cline, Claude Desktop, etc.), put credentials in the env block of your config — see MCP Client Configuration → npx.

MCP Streamable HTTP & SSE server (for remote / browser-based MCP clients)

# Streamable HTTP & SSE — listens on port 3444, endpoint: /mcp
GENIUS_CLIENT_ID=your_id \
GENIUS_CLIENT_SECRET=your_secret \
MUSIXMATCH_DIRECT_TOKEN='...' \
  npx -y --package mr-magic-mcp-server mcp-http-server

Connect your client to http://localhost:3444/mcp (or your public URL + /mcp).

The same server exposes the legacy SSE endpoints for older clients:

• GET /sse — opens the event stream

• POST /messages?sessionId=... — sends JSON-RPC messages

Both protocols run on the same port simultaneously — no extra config needed.

JSON HTTP automation server

# JSON HTTP — listens on port 3333, endpoint: POST /
GENIUS_CLIENT_ID=your_id \
GENIUS_CLIENT_SECRET=your_secret \
MUSIXMATCH_DIRECT_TOKEN='...' \
  npx -y --package mr-magic-mcp-server http-server

CLI

# Run a one-off CLI command
GENIUS_CLIENT_ID=your_id \
  npx -y --package mr-magic-mcp-server mrmagic-cli find --artist "Coldplay" --title "Yellow"

npx reference — all entrypoints

Option 3 — Global install (binaries always on PATH)

npm install -g mr-magic-mcp-server

mcp-server           # MCP stdio server
mcp-http-server      # Streamable HTTP & SSE MCP server (+ legacy SSE on same port)
http-server          # JSON HTTP automation server
mrmagic-cli --help   # CLI

When the binary is launched by an MCP client, it does not automatically read a .env file unless you point to one via MR_MAGIC_ENV_PATH. Either pass credentials through the client env block or set them as system/user environment variables.

Musixmatch token for npx / ephemeral / headless installs

When running via npx, on Render free tier, or on any server without a browser or persistent filesystem, the Musixmatch token cannot be captured via Playwright there. The workflow is:

1. Capture the token locally (one-time on any machine with a browser):

   git clone https://github.com/mrnajiboy/mr-magic-mcp-server.git
   cd mr-magic-mcp-server && npm install
   npm run fetch:musixmatch-token

   After signing in, the script prints the full token JSON payload. Copy the entire printed JSON object (the MUSIXMATCH_DIRECT_TOKEN=... line).

2. Push to KV so the server can read it on every cold start. Set up Upstash Redis (free tier at console.upstash.com) and run the push script with KV credentials. No browser needed:

   UPSTASH_REDIS_REST_URL=https://xxx.upstash.io \
   UPSTASH_REDIS_REST_TOKEN=your_upstash_token \
   MUSIXMATCH_DIRECT_TOKEN='<paste token JSON here>' \
     npm run push:musixmatch-token

3. Start the server with the same Upstash credentials — it reads the token from KV on every cold start (no MUSIXMATCH_DIRECT_TOKEN needed when KV is configured):

   GENIUS_DIRECT_TOKEN=... \
   UPSTASH_REDIS_REST_URL=https://xxx.upstash.io \
   UPSTASH_REDIS_REST_TOKEN=your_upstash_token \
     npx -y --package mr-magic-mcp-server mcp-http-server

4. Re-run steps 1–2 only when the Musixmatch token expires (typically ~30 days).

Musixmatch on Render (headless, no SSH)

On Render free tier you cannot SSH in or open a browser. The recommended pattern is:

1. Run npm run fetch:musixmatch-token locally, copy the token JSON from the output.

2. In the Render Dashboard → Environment tab, set:

   • MUSIXMATCH_DIRECT_TOKEN = <your token JSON> (used as both push source and runtime override)

   • UPSTASH_REDIS_REST_URL = your Upstash endpoint

   • UPSTASH_REDIS_REST_TOKEN = your Upstash token

3. Set the Render Start Command to:

   npm run push:musixmatch-token && npm run server:mcp:http

   On every (re)start, the token is pushed to Upstash then the server reads it from KV. If MUSIXMATCH_DIRECT_TOKEN is unset the push step is a silent no-op.

4. When the token expires: update MUSIXMATCH_DIRECT_TOKEN from a fresh local fetch:musixmatch-token run, trigger a redeploy on Render. Done.

Genius on ephemeral hosts: Genius does not need this flow. Set GENIUS_CLIENT_ID + GENIUS_CLIENT_SECRET instead — the server calls the Genius OAuth client_credentials endpoint at runtime, auto-refreshes the token in memory, and never needs a browser, a KV store, or a captured session token.

Environment Variables

Copy .env.example to .env (or inject via your platform dashboard). Variables are grouped below by purpose.

Genius credentials

Token resolution order (first match wins):

1. In-memory runtime cache

2. Auto-refresh via GENIUS_CLIENT_ID + GENIUS_CLIENT_SECRET ← recommended

3. GENIUS_DIRECT_TOKEN env var (static, no auto-refresh)

4. KV store — Upstash Redis or Cloudflare KV (written automatically by auto-refresh)

5. On-disk .cache/genius-token.json (local dev only)

Musixmatch credentials

Token resolution order (first match wins):

1. Env var — MUSIXMATCH_DIRECT_TOKEN

2. KV store — Upstash Redis (priority 1) or Cloudflare KV (priority 2)

3. On-disk cache — .cache/musixmatch-token.json (local dev / persistent servers)

Export and storage

Server and runtime

Airtable

Melon

Diagnostics and debugging

Provider Credentials

Genius

Genius credentials are resolved in this order — the first available source wins:

1. Auto-refresh (GENIUS_CLIENT_ID + GENIUS_CLIENT_SECRET) — the server calls the Genius OAuth client_credentials endpoint at runtime and keeps the token refreshed in memory. Recommended for all deployments, including Render and ephemeral hosts. No disk, no scripts, no manual token copying.

2. Direct token (GENIUS_DIRECT_TOKEN) — a static bearer token. Works everywhere but does not auto-refresh. Update by redeploying with a new value.

3. Cache token (.cache/genius-token.json) — written by npm run fetch:genius-token. Only suitable for local dev with a persistent filesystem.

Musixmatch

Musixmatch uses a captured browser session token. There is no OAuth callback.

For production / ephemeral hosts (Render, containers):

Set MUSIXMATCH_DIRECT_TOKEN directly in your environment. This is the highest-priority env var option and the only reliable one when the filesystem may be wiped between restarts.

For local development:

Run the fetch script once — it opens a Playwright-controlled Chromium window, signs you in, and writes the token to .cache/musixmatch-token.json:

npm run fetch:musixmatch-token

The workflow:

1. Run the script on any machine that can open a browser.

2. Sign in with Musixmatch (Google sign-in works) when prompted.

3. After the redirect to https://www.musixmatch.com/discover, the script prints the captured token and writes the cache file.

4. For remote deployments: copy the token value from the printed JSON and set it as MUSIXMATCH_DIRECT_TOKEN in your platform environment. Do not rely on the cache file surviving restarts on ephemeral hosts.

Developer accounts: Get API access from developer.musixmatch.com and set the resulting token as MUSIXMATCH_DIRECT_TOKEN.

Public accounts: Visit auth.musixmatch.com, sign in, and capture the token using the script above.

⚠️ WARNING: Calling the API from an unauthorized account may result in a ban.

Melon

Fetching Melon endpoints works anonymously. If MELON_COOKIE is blank, the server requests session cookies automatically. Set MELON_COOKIE to a complete cookie header string only when you need pinned, reproducible sessions.

Export and Download Configuration

The MR_MAGIC_EXPORT_BACKEND variable controls where formatted lyrics are stored:

• local (default) — writes files to MR_MAGIC_EXPORT_DIR (or exports/ when unset). Make sure the target directory is writable. The export_lyrics tool also returns the raw content field so clients can inline results when file writes fail. For global or npx CLI usage, the default exports/ directory is relative to the directory where you run mrmagic-cli, not the npm package install directory.

• inline — skips disk writes entirely. Each export is returned in the tool response with content populated and skipped: true to signal that persistence was intentionally bypassed.

• redis — stores exports in Upstash. Requires UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN, and MR_MAGIC_DOWNLOAD_BASE_URL.

For Redis exports, MR_MAGIC_DOWNLOAD_BASE_URL must be the publicly reachable base URL of the server that will serve the download links (not the Upstash URL), e.g. https://lyrics.example.com. Download links are built as {base_url}/downloads/{id}/{ext}.

Both HTTP servers serve /downloads/:id/:ext routes:

• server:mcp:http (port 3444) — the Streamable HTTP & SSE MCP server includes its own /downloads route. If you are already running this server, no additional HTTP server is needed for Redis exports on Render or any remote deployment.

• server:http (port 3333) — the JSON HTTP automation server also exposes the same route and remains the right choice if you are running server:mcp (stdio) only or want a standalone HTTP service for download links.

For local testing against the MCP HTTP server:

MR_MAGIC_DOWNLOAD_BASE_URL=http://127.0.0.1:3444

Or against the JSON HTTP server:

MR_MAGIC_DOWNLOAD_BASE_URL=http://127.0.0.1:3333

For global installs, start the JSON HTTP download server with the same persisted env file or environment variables used for export commands:

mrmagic-cli server --port 3333

Download URLs are only needed for the redis export backend. Local exports return file:// URLs and write files directly to MR_MAGIC_EXPORT_DIR or ./exports.

Local Deployment

Run whichever entrypoint you need via npm scripts:

npm run server:http        # JSON HTTP automation — 127.0.0.1:3333 by default
npm run server:mcp         # MCP stdio transport   — ideal for local MCP clients
npm run server:mcp:http    # Streamable HTTP & SSE MCP   — 127.0.0.1:3444 by default
npm run cli -- --help      # CLI entrypoint

Set provider tokens via .env before running. dotenv dependency is for local convenience only — production environments should inject vars directly.

Remote Deployment

Install dependencies and start the desired transport:

npm ci
npm run server:mcp:http    # or server:http / server:mcp

Use a process manager (systemd, PM2, Docker CMD, etc.) to keep servers running.

Deploying on Render

Both HTTP servers (server:mcp:http and server:http) are ready for Render with no extra network configuration. Render automatically sets:

When RENDER=true is detected, the server binds to 0.0.0.0 automatically and reads the platform-assigned PORT. No manual HOST or PORT configuration is needed.

The RENDER_EXTERNAL_HOSTNAME is automatically added to the DNS rebinding allowedHosts list so the MCP SDK does not emit host-validation warnings.

Recommended Render service settings:

• Start Command: npm run server:mcp:http

• Environment: set provider credentials (GENIUS_CLIENT_ID, GENIUS_CLIENT_SECRET, MUSIXMATCH_DIRECT_TOKEN, etc.) in the Render Dashboard → Environment tab

• Health Check Path: /health (returns { "status": "ok", "providers": [...] })

For custom domains, add them to MR_MAGIC_ALLOWED_HOSTS (comma-separated) in your Render environment so the DNS rebinding protection accepts requests with those Host headers.

Sessionless mode on Render (automatic)

When RENDER=true is detected, the MCP Streamable HTTP & SSE server automatically operates in sessionless mode. This is essential for multi-instance deployments where Render routes requests across several processes:

• An initialize request served by Instance A would store the session in A's in-memory Map. A follow-up tools/list call routed to Instance B cannot find that session and returns {"error": "Session not found. …"}.

• In sessionless mode, every request — initialize, tools/list, tools/call, etc. — is handled by a fresh, short-lived Server + StreamableHTTPServerTransport pair. No Mcp-Session-Id header is issued and no session state is stored. Each request is fully self-contained and works correctly regardless of which instance handles it.

You do not need to set MR_MAGIC_SESSIONLESS=1 manually on Render — it is auto-enabled via the platform-injected RENDER env var. Set MR_MAGIC_SESSIONLESS=1 explicitly on other multi-instance platforms (ECS, Fly.io, Railway, etc.) where a similar load-balanced, stateless deployment is used.

Transport selection

HTTP Endpoints

Both HTTP servers expose a set of plain HTTP routes in addition to their primary transports. These are accessible without any MCP or JSON-RPC framing.

/health

Both servers respond to GET /health with a JSON object indicating overall status and per-provider readiness. Use this as your Render (or container / load-balancer) health check path.

Response shape:

{
  "status": "ok",
  "providers": [
    { "name": "lrclib", "status": "ok" },
    { "name": "genius", "status": "ok" },
    { "name": "musixmatch", "status": "missing_token" },
    { "name": "melon", "status": "ok" }
  ]
}

MCP HTTP server (default port 3444):

curl -sS http://127.0.0.1:3444/health | jq

JSON HTTP server (default port 3333):

curl -sS http://127.0.0.1:3333/health | jq

Provider status values:

/downloads/:id/:ext

Serves a Redis-backed export file by its download ID and format extension. Both servers expose this route so the same MR_MAGIC_DOWNLOAD_BASE_URL works regardless of which server you are running.

Parameters:

• :id — the opaque download ID returned in the url field of an export response

• :ext — the file format: plain, lrc, srt, or romanized

Example (MCP HTTP server):

curl -sS http://127.0.0.1:3444/downloads/coldplay-yellow-1741234567890/plain

Example (JSON HTTP server):

curl -sS http://127.0.0.1:3333/downloads/coldplay-yellow-1741234567890/plain

Responses:

• 200 text/plain — export content served directly

• 404 — key expired or never written (MR_MAGIC_EXPORT_TTL_SECONDS controls TTL, default 3600 seconds)

• 400 — malformed path (missing ID or extension)

• 500 — Redis lookup error

Requires MR_MAGIC_EXPORT_BACKEND=redis and valid UPSTASH_* credentials. For local and inline backends, exports are returned directly in the tool response and this route is not used.

MCP Tools

Both the stdio and Streamable HTTP & SSE transports expose the same tool registry:

MCP search result behavior

search_lyrics and search_provider now return preview-only search results. They are intentionally compact and do not include full lyrics or raw provider payloads.

Each returned result is designed for follow-up tool calls and includes:

• core metadata such as provider, title, artist, album, duration, source URL, confidence, and synced/plain-only flags

• preview snippets (plainPreview / syncedPreview) when available

• a reusable reference object that can be passed back into downstream tools for exact result recall

The reference object is the durable handoff between search and resolution. Instead of copying large provider payloads around, clients can reuse the compact reference to resolve the exact provider result later.

MCP provider-reference workflow

After a search step, the following tools can resolve lyrics from either:

• direct track metadata

• a provider reference returned by search_lyrics or search_provider

• a selected match object from prior search output

This applies to:

• find_lyrics

• find_synced_lyrics

• build_catalog_payload

• format_lyrics

• export_lyrics

select_match in the workflow

select_match is the bridge between preview-only search results and the tools that resolve full lyrics.

It accepts any of these input shapes:

• items — grouped provider results returned by search_lyrics

• matches — flat results returned by search_provider (or other flattened match arrays)

• match — a single previously returned result passed through directly

Use criteria to narrow the choice by provider, require synced lyrics, and/or choose a zero-based index. The returned selected match can then be passed directly into find_lyrics, find_synced_lyrics, build_catalog_payload, format_lyrics, or export_lyrics. If you already know which result you want, you can skip select_match and pass that result's reference directly.

Example workflow: search → select → build/export

1. Call search_lyrics to get grouped, preview-only results plus provider reference objects.

2. Call select_match with the returned items to choose one result.

3. Pass the returned match into build_catalog_payload, find_lyrics, format_lyrics, or export_lyrics.

4. Optionally reuse the nested match.result.reference later to resolve the exact same provider result again without repeating the original broad search.

Example sequence:

{
  "track": { "artist": "Coldplay", "title": "Yellow" }
}

→ search_lyrics

{
  "items": [
    {
      "provider": "lrclib",
      "results": [
        {
          "title": "Yellow",
          "artist": "Coldplay",
          "synced": true,
          "reference": {
            "provider": "lrclib",
            "providerId": "...",
            "fingerprint": "..."
          }
        }
      ]
    }
  ],
  "criteria": { "requireSynced": true, "index": 0 }
}

→ select_match

{
  "match": {
    "provider": "lrclib",
    "result": {
      "title": "Yellow",
      "artist": "Coldplay",
      "reference": {
        "provider": "lrclib",
        "providerId": "...",
        "fingerprint": "..."
      }
    }
  },
  "options": {
    "omitInlineLyrics": true,
    "lyricsPayloadMode": "payload"
  }
}

→ build_catalog_payload

Or export the same exact result later with:

{
  "reference": {
    "provider": "lrclib",
    "providerId": "...",
    "fingerprint": "..."
  },
  "options": {
    "formats": ["plain", "lrc", "srt"]
  }
}

→ export_lyrics

Airtable Integration

Mr. Magic routes lyrics entirely server-side so long lyric text never passes through LLM tool-call arguments. This eliminates the JSON truncation and malformed-request errors that occur when multiline Korean / CJK lyrics are interpolated into payloads.

How it works

1. Call build_catalog_payload for each song. The response contains a lyricsCacheKey (e.g. kda-ill-show-you) that identifies the resolved lyrics in the server's in-memory LRU cache (20 entries, shared across the MCP session).

2. Create Airtable records (Song title, Spotify link, etc.) using your Airtable MCP's bulk create tools (up to 10 records per call). Capture the recordId returned for each created record.

3. Call push_catalog_to_airtable with recordId, lyricsFieldId, and lyricsCacheKey. The server looks up the cached lyrics and calls the Airtable REST API directly. Lyric text never leaves the server process as an MCP argument.

push_catalog_to_airtable call shape

{
  "baseId": "appeBUkVEp3N4RT0C",
  "tableId": "tbl0y5XHFXpjUJXHu",
  "recordId": "rec1234567890abcd",
  "fields": {},
  "lyricsFieldId": "fldHV1qmPYmsvglff",
  "lyricsCacheKey": "kda-ill-show-you",
  "preferRomanized": true
}

Set "splitLyricsUpdate": true when the combined create + lyrics payload is too large — this forces a two-step create → PATCH so the full payload is never sent in one request.

Bundled prompt template

prompts/airtable-song-importer.md (shipped in the source package) is a ready-to-use system prompt for MCP assistants that bulk-import songs into Airtable. It covers:

• Phased execution: resolve → bulk create → write lyrics → SRT export

• Bulk record creation up to 10 records per Airtable MCP call

• Spotify link resolution via the Spotify MCP

• Romanized lyric priority for K-pop / CJK content

• splitLyricsUpdate fallback for oversized payloads

Copy the file contents into your MCP client's system prompt to deploy immediately.

Safe lyric payload handoff

To avoid embedding raw lyric text in tool-call arguments, request a structured payload:

{
  "track": { "artist": "K/DA", "title": "I'll Show You" },
  "options": {
    "omitInlineLyrics": true,
    "lyricsPayloadMode": "payload"
  }
}

Option reference:

• omitInlineLyrics: true — removes lyrics, plainLyrics, and romanizedPlainLyrics from the response, keeping it compact.

• lyricsPayloadMode: "payload" — adds a lyricsPayload object with the full text inline (transport: "inline"). May auto-promote to "reference" for long lyrics when omitInlineLyrics is also true.

• lyricsPayloadMode: "reference" — stores lyrics via the export backend and returns a lyricsPayload.reference object with filePath or url instead of raw text.

• airtableSafePayload: true — adds lyricsPayload.airtableEscapedContent (quotes / backslashes / newlines pre-escaped) and prefers compact / reference-style handoff.

Important: tools/call.params.arguments must be a plain JSON object. Do not pre-serialize arguments into a string — build_catalog_payload and select_match reject stringified payloads.

Calling patterns

Preferred (MCP SDK):

await client.callTool({
  name: 'build_catalog_payload',
  arguments: {
    track: { artist: 'K/DA', title: "I'll Show You" },
    options: { omitInlineLyrics: true, lyricsPayloadMode: 'payload', airtableSafePayload: true }
  }
});

Also valid (raw fetch, object-based):

await fetch('http://127.0.0.1:3444/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: {
      name: 'build_catalog_payload',
      arguments: {
        track: { artist: 'K/DA', title: "I'll Show You" },
        options: { omitInlineLyrics: true, lyricsPayloadMode: 'payload', airtableSafePayload: true }
      }
    }
  })
});

Avoid: manual JSON string templates that interpolate multiline lyrics.

Debugging truncated arguments

Enable chunk logging to diagnose malformed / truncated MCP tool arguments:

MR_MAGIC_LOG_TOOL_ARGS_CHUNKS=1
MR_MAGIC_TOOL_ARG_CHUNK_SIZE=400
LOG_LEVEL=debug

Recommended presets:

MCP Client Configuration

Mr. Magic supports two connection modes depending on where the MCP client runs:

Configuration modes at a glance

The right way to supply environment variables depends on how the server is launched:

npx and MCP clients: When a local MCP client (Cline, Claude Desktop, etc.) starts the server via npx, the spawned process has no access to your .env file — your project root and shell environment are not inherited. Every required variable must be provided in the env block of your MCP client config. See the npx snippet below.

Required variables by deployment type

Ephemeral / npx / stateless hosts (no persistent filesystem)

These variables should be passed explicitly — the server cannot fall back to .env or on-disk caches:

💡 Musixmatch on ephemeral hosts: The on-disk token cache (.cache/musixmatch-token.json) is not available when running via npx or on ephemeral servers. Use MUSIXMATCH_DIRECT_TOKEN directly, or configure Upstash Redis (UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN) and run push:musixmatch-token once to store the token in KV. See Musixmatch token for npx / ephemeral / headless installs.

Local source / persistent servers (writable filesystem present)

In addition to the provider credentials above, local and persistent deployments can also use:

On-disk token caches (.cache/genius-token.json, .cache/musixmatch-token.json) are also read automatically when a persistent filesystem is available and the above env vars are not set.

Local clients (stdio)

⚠️ Stdio MCP clients: Always invoke the server binary directly — never via npm run server:mcp. The npm script preamble (> mr-magic-mcp-server@x.x.x …) is written to stdout before Node starts, and stdio MCP clients try to parse every stdout line as JSON-RPC, causing "Unexpected token '>'" errors on every connection.

npx (no clone required)

Works with any local MCP client that supports command / args. Because this package publishes multiple binaries, you must use --package to name the package and then explicitly name the mcp-server binary. This is the correct form — do not use npx -y mr-magic-mcp-server (no binary by that name exists).

⚠️ npx does not read your local .env file. The process is spawned by the MCP client and has no access to your project directory or shell environment. All credentials and configuration must be provided in the env block below. For a simpler setup, prefer Local repo — Cline which reads .env automatically.

{
  "mcpServers": {
    "Mr. Magic": {
      "command": "npx",
      "args": ["-y", "--package", "mr-magic-mcp-server", "mcp-server"],
      "env": {
        "MR_MAGIC_QUIET_STDIO": "1",

        "GENIUS_CLIENT_ID": "...",
        "GENIUS_CLIENT_SECRET": "...",

        "MUSIXMATCH_DIRECT_TOKEN": "...",

        "UPSTASH_REDIS_REST_URL": "https://xxx.upstash.io",
        "UPSTASH_REDIS_REST_TOKEN": "...",

        "AIRTABLE_PERSONAL_ACCESS_TOKEN": "..."
      }
    }
  }
}

Variable notes:

• MR_MAGIC_QUIET_STDIO=1 — always set this for stdio clients. Suppresses non-error stdout so the MCP client doesn't see log lines as JSON-RPC noise.

• GENIUS_CLIENT_ID + GENIUS_CLIENT_SECRET — recommended for auto-refresh. Use GENIUS_DIRECT_TOKEN instead for a static token (no auto-refresh).

• MUSIXMATCH_DIRECT_TOKEN — required if using Musixmatch. Must be the full token JSON payload (from npm run fetch:musixmatch-token). Omit only if you've already pushed the token to a KV store via push:musixmatch-token (then supply UPSTASH_* and the KV lookup handles it at runtime).

• UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN — optional but recommended: enables KV-backed Musixmatch token storage (so you can refresh the token without updating the client config) and unlocks the redis export backend.

• AIRTABLE_PERSONAL_ACCESS_TOKEN — only required if using push_catalog_to_airtable.

Minimal config (Genius + Musixmatch, no Airtable, no Redis):

{
  "mcpServers": {
    "Mr. Magic": {
      "command": "npx",
      "args": ["-y", "--package", "mr-magic-mcp-server", "mcp-server"],
      "env": {
        "MR_MAGIC_QUIET_STDIO": "1",
        "GENIUS_CLIENT_ID": "...",
        "GENIUS_CLIENT_SECRET": "...",
        "MUSIXMATCH_DIRECT_TOKEN": "..."
      }
    }
  }
}

Global install

After npm install -g mr-magic-mcp-server, the mcp-server binary is on PATH. When launched by an MCP client, the global binary can read a .env file if MR_MAGIC_ENV_PATH points to one — otherwise pass credentials via the env block just like the npx config above, or set them as system/user-level environment variables so they're available to all spawned processes.

{
  "mcpServers": {
    "Mr. Magic": {
      "command": "mcp-server",
      "env": {
        "MR_MAGIC_QUIET_STDIO": "1",
        "GENIUS_CLIENT_ID": "...",
        "GENIUS_CLIENT_SECRET": "...",
        "MUSIXMATCH_DIRECT_TOKEN": "..."
      }
    }
  }
}

Or, if you keep a .env file somewhere on disk:

{
  "mcpServers": {
    "Mr. Magic": {
      "command": "mcp-server",
      "env": {
        "MR_MAGIC_QUIET_STDIO": "1",
        "MR_MAGIC_ENV_PATH": "/Users/you/.config/mr-magic/.env"
      }
    }
  }
}

Local repo — Cline

Cline supports cwd, so you can invoke node directly. The server reads .env from the project root automatically — no env block needed for credentials you've already set there (though you may still want MR_MAGIC_QUIET_STDIO):

{
  "mcpServers": {
    "Mr. Magic": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "node",
      "args": ["src/bin/mcp-server.js"],
      "cwd": "/Users/you/Documents/Code/MCP/mr-magic-mcp-server",
      "env": {
        "MR_MAGIC_QUIET_STDIO": "1"
      }
    }
  }
}

Local repo — clients without cwd support

For local clients that don't support a working-directory option, use a shell wrapper. The cd sets the project root so .env is found automatically:

{
  "mcpServers": {
    "Mr. Magic": {
      "command": "/bin/sh",
      "args": ["-c", "cd /Users/you/Code/mr-magic-mcp-server && node src/bin/mcp-server.js"],
      "env": {
        "MR_MAGIC_QUIET_STDIO": "1"
      }
    }
  }
}

Remote clients (Streamable HTTP & SSE)

When Mr. Magic is deployed on a remote host (Render, VPS, etc.), connect via the Streamable HTTP & SSE MCP endpoint (/mcp). Credentials are configured server-side via environment variables — no env block is needed in the client config.

Generic remote client (URL-based config)

Any client that accepts a plain MCP endpoint URL:

https://your-server.com/mcp

Legacy SSE clients

Some older MCP clients use the pre-Streamable HTTP & SSE SSE protocol instead of POST /mcp. For those, use the legacy SSE endpoint:

GET  https://your-server.com/sse        ← opens the event stream
POST https://your-server.com/messages   ← sends JSON-RPC messages

The server supports both protocols simultaneously — no restart or reconfiguration needed.

TypingMind

TypingMind connects to remote MCP servers through its MCP Connector browser extension (Chrome / Edge). Once your server is deployed:

1. Open TypingMind → Plugins → MCP Servers → Add MCP Server.

2. Set the endpoint URL to your deployed server's /mcp path, e.g.:

   https://your-server.com/mcp

3. Leave authentication blank (credentials are set server-side via environment variables on the deployed instance).

4. Save and enable the server.

"Update required. Please restart your MCP Connector…"

This message is displayed by the TypingMind MCP Connector extension itself — it is not a Mr. Magic error. It means the installed version of the extension predates remote MCP server support. Fix: restart the MCP Connector extension (click the extension icon → restart, or disable and re-enable it in your browser's Extensions settings). If the message persists, update the extension from the Chrome / Edge Web Store. No changes to Mr. Magic or your server configuration are required.

CLI

A single CLI entrypoint (mrmagic-cli) is published with the package. Inside the local repo use npm run cli -- <subcommand> unless you have run npm link or installed globally.

Global CLI options:

• --env-path <path> / --env-file <path> — load credentials from a custom .env file before running the command. This is useful for global installs, npm link, and npx usage where the package install directory is not your project directory.

• --save-env-path — persist the provided --env-path to ~/.config/mrmagic-cli/config.json so future mrmagic-cli commands load the same credentials file automatically.

Commands

Examples

# Search all providers
npm run cli -- search --artist "BLACKPINK" --title "Kill This Love"

# Global/custom install with an explicit credential file
mrmagic-cli --env-path /absolute/path/to/.env find --artist "Nayeon" --title "POP!"

# Save that credential file path once for future global CLI commands
mrmagic-cli --env-path /absolute/path/to/.env --save-env-path status

# Find best lyric (prefers synced LRC)
npm run cli -- find --artist "Nayeon" --title "POP!"

# Export plain text and SRT files for the best match
npm run cli -- export --artist "Nayeon" --title "POP!" --format plain --format srt --output ./exports

# Global install: local export files are written to ./exports relative to your shell's current directory
mrmagic-cli export --artist "Nayeon" --title "POP!" --format srt

# Global install: Redis-backed download URLs served by the JSON HTTP server
MR_MAGIC_EXPORT_BACKEND=redis \
MR_MAGIC_DOWNLOAD_BASE_URL=http://127.0.0.1:3333 \
  mrmagic-cli export --artist "Nayeon" --title "POP!" --format srt

mrmagic-cli server --port 3333

# Pick first synced match from a prioritized provider list
npm run cli -- select --providers lrclib,genius --artist "Nayeon" --title "POP!" --require-synced

# Start JSON automation API on a custom port
mrmagic-cli server --port 4000

npm argument forwarding

Both of these forms work:

npm run cli search --artist "K/DA" --title "I'll Show You"
npm run cli -- search --artist "K/DA" --title "I'll Show You"

For direct binary usage: mrmagic-cli search --artist "K/DA" --title "I'll Show You".

Manual Testing

Automated checks:

npm run test                             # full bundled test runner
node src/tests/mcp-tools.test.js         # raw MCP integration harness
npm run repro:mcp:arg-boundary           # JSON-RPC argument boundary repro
npm run repro:mcp:arg-boundary:sdk       # SDK client transport repro
npm run lint
npm run format:check

JSON HTTP server (server:http)

Start the server:

npm run server:http

Default base URL: http://127.0.0.1:3333

Accepted requests:

• GET /health

• POST / with body { "action": "find|findSynced|search", "track": {...}, "options": {...} }

Health check

curl -sS http://127.0.0.1:3333/health | jq

Basic lyric lookup (action=find)

curl -sS -X POST http://127.0.0.1:3333 \
  -H 'Content-Type: application/json' \
  -d '{"action":"find","track":{"artist":"Coldplay","title":"Yellow"},"options":{}}' | jq

Synced-only lookup (action=findSynced)

curl -sS -X POST http://127.0.0.1:3333 \
  -H 'Content-Type: application/json' \
  -d '{"action":"findSynced","track":{"artist":"Coldplay","title":"Yellow"},"options":{}}' | jq

Search candidates (action=search)

curl -sS -X POST http://127.0.0.1:3333 \
  -H 'Content-Type: application/json' \
  -d '{"action":"search","track":{"artist":"Coldplay","title":"Yellow"}}' | jq

Export flow

curl -sS -X POST http://127.0.0.1:3333 \
  -H 'Content-Type: application/json' \
  -d '{"action":"find","track":{"artist":"Coldplay","title":"Yellow"},"options":{"export":true,"formats":["plain"]}}' | jq

Look for exports.plain in the response:

• redis backend: url field present, skipped: false

• local backend: filePath field present

• inline backend: content field present, skipped: true

To fetch a Redis export download:

EXPORT_URL=$(curl -sS -X POST http://127.0.0.1:3333 \
  -H 'Content-Type: application/json' \
  -d '{"action":"find","track":{"artist":"Coldplay","title":"Yellow"},"options":{"export":true,"formats":["plain"]}}' \
  | jq -r '.exports.plain.url')

curl -sS "$EXPORT_URL" | head -n 10

MCP Streamable HTTP & SSE server (server:mcp:http)

Start the server:

npm run server:mcp:http

Default endpoint: http://127.0.0.1:3444/mcp

All requests are JSON-RPC 2.0. Required headers:

Content-Type: application/json
Accept: application/json, text/event-stream

Tip: use --sessionless for easier stateless manual testing: npm run cli -- server:mcp:http --sessionless

Health check

curl -sS http://127.0.0.1:3444/health | jq

List tools

curl -sS -X POST http://127.0.0.1:3444/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq

find_lyrics

Accepts either direct track metadata, a provider reference from prior search output, or a selected match.

curl -sS -X POST http://127.0.0.1:3444/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"find_lyrics","arguments":{"track":{"artist":"Coldplay","title":"Yellow"}}}}' | jq

find_synced_lyrics

Same lookup inputs as find_lyrics, but only returns timestamped results.

curl -sS -X POST http://127.0.0.1:3444/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"find_synced_lyrics","arguments":{"track":{"artist":"Coldplay","title":"Yellow"}}}}' | jq

build_catalog_payload — inline lyrics

Accepts direct track metadata, a reusable reference, or a selected match from prior search output.

curl -sS -X POST http://127.0.0.1:3444/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc":"2.0","id":4,"method":"tools/call",
    "params":{"name":"build_catalog_payload","arguments":{"track":{"artist":"K/DA","title":"I'\''LL SHOW YOU"},"options":{"preferRomanized":false}}}
  }' | jq

build_catalog_payload — Airtable-safe mode

curl -sS -X POST http://127.0.0.1:3444/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc":"2.0","id":5,"method":"tools/call",
    "params":{"name":"build_catalog_payload","arguments":{"track":{"artist":"K/DA","title":"I'\''LL SHOW YOU"},"options":{"omitInlineLyrics":true,"lyricsPayloadMode":"payload","airtableSafePayload":true}}}
  }' | jq

search_lyrics

Returns grouped, preview-only results under items. Each result includes a reusable reference, plus compact metadata and previews when available. Full lyrics and raw provider payloads are intentionally omitted.

curl -sS -X POST http://127.0.0.1:3444/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"search_lyrics","arguments":{"track":{"artist":"Coldplay","title":"Yellow"}}}}' | jq

search_provider

Returns a flat matches array with the same preview-only result shape used by the grouped search_lyrics output.

curl -sS -X POST http://127.0.0.1:3444/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"search_provider","arguments":{"provider":"lrclib","track":{"artist":"Coldplay","title":"Yellow"}}}}' | jq

format_lyrics

Accepts direct track metadata, a reusable reference, or a selected match.

curl -sS -X POST http://127.0.0.1:3444/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"format_lyrics","arguments":{"track":{"artist":"aespa","title":"Supernova"},"options":{"includeSynced":true}}}}' | jq

export_lyrics

Accepts direct track metadata, a reusable reference, or a selected match.

curl -sS -X POST http://127.0.0.1:3444/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"export_lyrics","arguments":{"track":{"artist":"Coldplay","title":"Yellow"},"options":{"formats":["plain","lrc","srt"]}}}}' | jq

get_provider_status

curl -sS -X POST http://127.0.0.1:3444/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"get_provider_status","arguments":{}}}' | jq

runtime_status

curl -sS -X POST http://127.0.0.1:3444/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"runtime_status","arguments":{}}}' | jq

push_catalog_to_airtable

First call build_catalog_payload to populate the lyric cache and capture lyricsCacheKey, then pass it here — no lyric text goes through tool-call arguments:

curl -sS -X POST http://127.0.0.1:3444/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc":"2.0","id":12,"method":"tools/call",
    "params":{"name":"push_catalog_to_airtable","arguments":{
      "baseId":"appeBUkVEp3N4RT0C",
      "tableId":"tbl0y5XHFXpjUJXHu",
      "recordId":"rec1234567890abcd",
      "fields":{},
      "lyricsFieldId":"fldHV1qmPYmsvglff",
      "lyricsCacheKey":"kda-ill-show-you",
      "preferRomanized":true
    }}
  }' | jq

Replace baseId, tableId, recordId, lyricsFieldId, and lyricsCacheKey with real values. Requires AIRTABLE_PERSONAL_ACCESS_TOKEN.

select_match

Use items for grouped search_lyrics output, matches for flat search_provider output, or match to pass through a single result directly.

curl -sS -X POST http://127.0.0.1:3444/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc":"2.0","id":13,"method":"tools/call",
    "params":{"name":"select_match","arguments":{
      "matches":[{"provider":"lrclib","result":{"title":"Yellow","artist":"Coldplay","synced":true,"plainOnly":false}}],
      "criteria":{"requireSynced":true,"index":0}
    }}
  }' | jq

Example using grouped items from search_lyrics:

curl -sS -X POST http://127.0.0.1:3444/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc":"2.0","id":14,"method":"tools/call",
    "params":{"name":"select_match","arguments":{
      "items":[{"provider":"lrclib","results":[{"title":"Yellow","artist":"Coldplay","synced":true,"reference":{"provider":"lrclib","providerId":"123","fingerprint":"abc"}}]}],
      "criteria":{"requireSynced":true,"index":0}
    }}
  }' | jq

MCP tool response shape:

• result.structuredContent — machine-friendly object (all fields, full values)

• result.content[0].text — complete pretty-printed JSON (identical to structuredContent)

Both channels carry the same complete payload. Programmatic consumers should prefer structuredContent; LLM agents reading content[0].text get the full JSON string.

Running both servers side-by-side

You may want both servers running at the same time — for example, to serve JSON HTTP automations (server:http) alongside MCP tool calls (server:mcp:http), or to expose both a REST API and an MCP endpoint under one deployment.

# Terminal 1
npm run server:http       # JSON HTTP automation — port 3333

# Terminal 2
npm run server:mcp:http   # Streamable HTTP & SSE MCP  — port 3444

Note: Running both is not required for Redis exports. The MCP HTTP server (server:mcp:http) includes its own /downloads/:id/:ext route, so a single server:mcp:http instance is self-sufficient for Redis-backed download links. Only run server:http alongside it if you also need the JSON HTTP automation API.

Changelog

See CHANGELOG.md for a full history of changes.

License

MIT

I am not and cannot be held liable for any infringement or ban from services that could occur as a result of using this software. Your usage is solely your responsibility. Godspeed.

© 2026 Kenyatta Naji Johnson-Adams