# Magic Master MCP — audio mastering for AI agents

[![Magic Master — Audio Mastering MCP server](https://mcprush.com/badge/magic-master-audio-mastering-mcp/card.svg)](https://mcprush.com/to/magic-master-audio-mastering-mcp?ref=badge)

Remote [MCP](https://modelcontextprotocol.io) server that lets Claude, ChatGPT, Cursor, VS Code, Claude Code, OpenAI Codex and any other MCP client **master audio**: hit a loudness (LUFS) target with True Peak limiting, remove the **Suno / Udio AI fingerprint**, compare presets on a 24-second preview, and master a whole album with consistent relative loudness. Results come back with measured numbers and a mastering passport in the chat.

- Server: `https://magicmaster.pro/mcp` (streamable HTTP; protocol revisions `2026-07-28`, `2025-11-25`, `2025-06-18`)
- OAuth endpoint (for clients that cannot send headers, e.g. Claude Desktop custom connectors): `https://magicmaster.pro/mcp/oauth`
- Agent playbook: <https://magicmaster.pro/agents.md> · machine manifest: <https://magicmaster.pro/agent.json> · OpenAPI (public subset): <https://magicmaster.pro/openapi-public.json>
- Human page (RU/EN): <https://magicmaster.pro/mcp>
- Service version: 3.15.0 (as reported by `get_service_info`)

Nothing to install: the server is hosted. This repository holds the connection recipes and a small stdio bridge for clients that cannot speak HTTP.

## Tools

The server exposes 11 tools. Descriptions below are condensed from the live `tools/list`; the live text is authoritative.

| Tool | What it does | Cost |
|---|---|---|
| `get_service_info` | What Magic Master does, what is free, what costs a token, and where the rules live. Call once at the start of a session. | free |
| `list_presets` | All 24 mastering presets with their target loudness in LUFS. Gives the exact keys that `master_track` and `batch_master` accept. | free |
| `get_pricing` | Live token packs and payment methods (RUB). Prices are read live, not quoted from memory. | free |
| `check_limits` | Token balance, free quota left and when it resets, upload cap, whether PRO modules are available. | free |
| `analyze_track` | Integrated LUFS, sample peak, duration, sample rate and stereo correlation, without processing. True peak and loudness range come back from `get_job` after mastering. | free |
| `clean_ai_trace` | Strips the Suno / Udio AI generator fingerprint; loudness and tone stay as they are. Returns a job id. | free |
| `preview_styles` | Masters the middle 24 seconds in 2–6 presets at once and returns each one's loudness and a listen link. | free, 6 per day |
| `master_track` | Masters one track. Costs 1 token when the account has a balance; otherwise it runs on the free quota without PRO modules. Returns a job id. Pass `dry_run=true` to see the price and effective settings first. | 1 token |
| `batch_master` | Masters up to 10 tracks in one call with the same settings. `album_mode` (default `true`) keeps relative loudness between tracks. Returns one job id per track. | 1 token per track |
| `get_job` | Status, progress and result metrics (`after_lufs`, `true_peak_db`, `lra`, `platform_ready`) for a mastering, cleanup or preview job. Includes a signed `download_url` when a master is done. | free |
| `create_topup_link` | Prepares a token checkout for the human. The agent cannot complete the payment itself. | free |

Typical flow: `analyze_track` → (`clean_ai_trace` for AI-generated tracks) → optionally `preview_styles` → `master_track` → poll `get_job`.

## Endpoints and authentication

| Endpoint | Auth | Use it when |
|---|---|---|
| `https://magicmaster.pro/mcp` | none, or `X-API-Key: mm_…` | you write the code, you use Claude Code / Cursor / VS Code / Codex with a header, or you only need the free tools |
| `https://magicmaster.pro/mcp/oauth` | OAuth 2.1 (authorization code + PKCE `S256`, scope `mastering`) | your client cannot send custom headers (Claude Desktop, ChatGPT connectors) |

- Without any key, the free tools work on `/mcp`.
- On `/mcp`, `Authorization: Bearer` means an **OAuth access token**. An account JWT sent there returns `401`, and it breaks even the free calls. Use `X-API-Key` on `/mcp`, or connect through `/mcp/oauth`.
- `/mcp/oauth` answers an unauthenticated request with `401` and a `WWW-Authenticate` challenge pointing at `https://magicmaster.pro/.well-known/oauth-protected-resource`, so a compliant client starts the sign-in on its own.
- OAuth metadata: `/.well-known/oauth-authorization-server`; dynamic client registration: `/oauth/register`. Access tokens last one hour; refresh tokens rotate on every use. Tokens are issued for the resource `https://magicmaster.pro/mcp` only.
- API keys (`mm_…`) are issued in the profile after a token purchase; up to 10 active keys.

## Install

**Claude Code**

```bash
claude mcp add --transport http magicmaster https://magicmaster.pro/mcp
```

Free tools work immediately. For the paid tools, add your key:

```bash
claude mcp add --transport http magicmaster https://magicmaster.pro/mcp --header "X-API-Key: mm_YOUR_KEY"
```

**Claude Desktop and claude.ai (custom connector, OAuth)**

Settings → Connectors → *Add custom connector* → URL `https://magicmaster.pro/mcp/oauth` → sign in on the consent page. Use `https://magicmaster.pro/mcp` if you only need the free tools.

**Claude Desktop through a stdio bridge** (if you prefer the config file)

```json
{
  "mcpServers": {
    "magicmaster": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://magicmaster.pro/mcp/oauth"]
    }
  }
}
```

**Cursor (`.cursor/mcp.json`)**

```json
{ "mcpServers": { "magicmaster": { "url": "https://magicmaster.pro/mcp" } } }
```

**VS Code (`.vscode/mcp.json`)**

```json
{ "servers": { "magicmaster": { "type": "http", "url": "https://magicmaster.pro/mcp" } } }
```

**OpenAI Codex (`~/.codex/config.toml`)**

```toml
[mcp_servers.magicmaster]
url = "https://magicmaster.pro/mcp"
```

**ChatGPT (Developer mode → Connectors → Create):** URL `https://magicmaster.pro/mcp/oauth`, authentication OAuth.

**stdio-only clients** — the npm package wraps the same bridge:

```json
{ "mcpServers": { "magicmaster": { "command": "npx", "args": ["-y", "magicmaster-mcp"] } } }
```

The bridge points at `https://magicmaster.pro/mcp/oauth` by default. Set `MAGICMASTER_MCP_URL=https://magicmaster.pro/mcp` to use the anonymous endpoint instead.

One-click buttons: [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=magicmaster&config=eyJ1cmwiOiJodHRwczovL21hZ2ljbWFzdGVyLnByby9tY3AifQ==) · VS Code: `vscode:mcp/install?{"name":"magicmaster","type":"http","url":"https://magicmaster.pro/mcp"}`

## Docker

For clients without Node, and for the Glama build that runs security checks:

```bash
docker build -t magicmaster-mcp .
docker run -i --rm magicmaster-mcp
```

The image holds only the bridge; the server itself stays hosted at `https://magicmaster.pro/mcp`. It is built from this repository (`npm ci`), so `mcp-remote` is baked in and the container needs only outbound HTTPS to `magicmaster.pro` at run time. The image defaults to the anonymous endpoint. To use OAuth (which also unlocks the paid tools), run it with `-e MAGICMASTER_MCP_URL=https://magicmaster.pro/mcp/oauth`.

Build spec for a Glama release (the platform configures the recipe on its side, it does not read this Dockerfile):

- build steps: `npm ci --omit=dev`
- start command: `node bin/magicmaster-mcp.js`
- environment: `MAGICMASTER_MCP_URL=https://magicmaster.pro/mcp`

## Free vs tokens

- **Free, no account:** `analyze_track`, `clean_ai_trace`, `preview_styles` (6 per day), `get_job`, `get_pricing`, `list_presets`, `get_service_info`, `check_limits`, `create_topup_link`.
- **Guest mastering (no account):** 3 basic masters per calendar month per IP. Basic means no PRO modules.
- **Free account:** 1 master per UTC day (3 during the first 24 hours after sign-up). Also basic.
- **Trial for agents:** registering an agent once (`POST /api/agents/register`, with the account's JWT as `Authorization: Bearer`) grants 3 full PRO masters and an API key. The MCP connector does not grant the trial; only that call does. See `agents.md`.
- **Tokens:** 1 token = 1 full PRO master (any preset, all PRO modules, any export format). Tokens never expire. There are no subscriptions. Some packs include bonus tokens. Live packs and prices: `get_pricing` (RUB) or `GET https://magicmaster.pro/api/tokens/packages`.
- **Payment needs the human.** An agent cannot complete a card payment. Call `create_topup_link`, hand the checkout link to the person, then poll `check_limits` until the balance is credited. A card issued outside Russia may be declined; see `https://magicmaster.pro/wallet`.
- `master_track` and `batch_master` accept `dry_run=true`, which reports the price and the effective settings without spending anything.

## Formats, limits and retention

- **Input** (from `agent.json`): `aac`, `aif`, `aiff`, `amr`, `flac`, `m4a`, `mp3`, `ogg`, `wav`, `webm`. Detection is by content.
- **Output:** `wav`, `wav24`, `mp3`, `flac`, `opus`, `aac`. MP3 bitrates 128/192/256/320; Opus 128/192.
- **Upload caps:** on the site and API, 160 MB without payment; after a token purchase up to 1000 MB (WAV). Through this MCP server, `master_track` and `batch_master` accept up to **100 MB per file** and `batch_master` up to **300 MB per call** (10 tracks). `check_limits` returns the effective per-channel ceiling (`max_upload_mb_via_mcp`).
- **Audio source:** a public `https` URL (`audio_url`). Share links to Suno/Udio song pages, Google Drive and Dropbox are resolved to the file.
- **Retention of finished masters:** guest results are kept only briefly (in memory); free accounts 1 day; after a token purchase 30 days. `get_job` returns a signed `download_url` for about an hour, which works without credentials.
- **Typical time:** 20–60 s per master; up to 10 minutes for a long track with restoration. Poll `get_job`, or pass `webhook_url` to `master_track` to get a POST instead.

## Mastering options

- **Presets** (24, from `list_presets`): e.g. `standard` (−14 LUFS), `edm` (−9), `pop` (−12), `hiphop` (−13), `podcast` (−16), `unlimiter` (−12), `voice` (−16), `audiobook` (−19). Use `preview_styles` to compare two to six of them on 24 seconds for free.
- **Target loudness:** `target_lufs` overrides the preset, e.g. `-14` for Spotify. True Peak limiting follows ITU-R BS.1770-5.
- **Output:** `out_format`, `bitrate`, `dither_type` (`tpdf`, `ns_e`, `ns_itu`, for 16-bit WAV).
- **Density:** `intensity` from 0.5 (gentler) to 1.5 (denser); 1.0 is the preset as designed.
- **Restoration:** `restore_dynamics` opens up a brickwalled source before mastering (pairs with the `unlimiter` preset). `denoise_strength` (0–1) sets noise reduction; 0 disables it. The web restoration page also lists de-hum and de-click steps, which the MCP tools do not expose by name.
- **Suno / Udio cleanup:** `remove_watermark=true` on `master_track` and `batch_master` also removes the AI fingerprint, free of charge. The standalone tool is `clean_ai_trace`.
- **Album mode:** `batch_master` with `album_mode` (default `true`): the loudest track hits the target and the others keep their offsets, so a quiet interlude is not inflated to single level. Use `album_mode=false` for unrelated singles.

## What is not in MCP

These features are on the website (or in the API) but are **not MCP tools**:

- Stem mastering (2–8 stems combined and mastered as one track): API `POST /api/v2/master/stems`, 1 token.
- Free vocal removal and stem split on the web: <https://magicmaster.pro/stems-separation> (free; a free account gets four stems).
- Key changer, −6…+6 semitones, free: <https://magicmaster.pro/tools/key-changer>.
- Audio cutter, free: <https://magicmaster.pro/tools/audio-cutter>.
- Clipping check (free) and De-clipper: <https://magicmaster.pro/declipper>.
- Release-ready check: <https://magicmaster.pro/release-ready>. **Not launched yet**: requests are open, nothing is charged.
- Mixing with a live engineer: <https://magicmaster.pro/mixing-engineer>. **Not launched yet**: requests are open, nothing is charged.

## Links

Terms <https://magicmaster.pro/terms> · Privacy <https://magicmaster.pro/privacy> · Pricing <https://magicmaster.pro/pricing> · Developer API <https://magicmaster.pro/developers> · Support support@magicmaster.pro

---

## Changelog

### 0.3.2

- Tool list documented as the live 11 tools: adds `preview_styles` (free comparison, 6 per day) and `batch_master` (album mode, up to 10 tracks per call); both were missing from the 0.3.0 README.
- README: Codex, Claude Code with API key header, and OAuth details (`/mcp/oauth`, PKCE, scope `mastering`) added; limits and formats taken from the live manifest.
- Bridge (`bin/magicmaster-mcp.js`) uses the bundled `mcp-remote` dependency when it is installed; it falls back to `npx` only when it is not.
- Package metadata: description and keywords extended.

---

### По-русски

Удалённый MCP-сервер Magic Master для AI-агентов и клиентов вроде Claude, ChatGPT, Cursor, VS Code, Claude Code и Codex. Он выводит трек на целевую громкость (LUFS) с ограничением True Peak, снимает цифровой след Suno/Udio, сравнивает пресеты на 24-секундном отрывке и мастерит целый альбом с сохранением относительной громкости. Ставить ничего не нужно — адрес `https://magicmaster.pro/mcp`.

- **Бесплатно:** анализ, снятие следа ИИ, сравнение пресетов (6 раз в сутки), статус задач, цены и лимиты.
- **Платно:** 1 токен = 1 полный PRO-мастеринг. Токены не сгорают, подписок нет. Актуальные цены — инструмент `get_pricing` (в рублях). Оплату проводит человек по ссылке из `create_topup_link`.
- **Подключение:** Claude Code — `claude mcp add --transport http magicmaster https://magicmaster.pro/mcp`; Claude Desktop и claude.ai — пользовательский коннектор на `https://magicmaster.pro/mcp/oauth`.
- Подробности и подключение по-русски: <https://magicmaster.pro/mcp>. Поддержка: support@magicmaster.pro.