Skip to main content
Glama
ope-olatunji

audio-mastering-mcp

by ope-olatunji

Earn with OpenCrater — earn free AI compute for the Blips you see in Claude Code, Codex & other AI terminals, and monetize your own CLI, MCP server or agent

audio-mastering-mcp

npm version license

An MCP server that masters audio with a real, professional signal chain — powered entirely by ffmpeg, no DAW required. Give it a rough mix (or a vocal + a beat) and get back a clean, loud, release-ready master, an immersive wide-stereo version, and Dolby-codec exports.

It exists because letting an AI assistant "master a track" usually means hand-waving. This makes it concrete: a fixed, well-reasoned chain (corrective EQ → glue compression → multiband compression → saturation → exciter → stereo stage → limiter), finished with two-pass loudnorm so loudness and true-peak land on an exact target every time.


Table of contents


Related MCP server: reaper-mcp

Features

  • analyze_loudness — measure integrated loudness (LUFS), true peak (dBTP), loudness range (LRA), and gating threshold.

  • mix_vocal_over_beat — lay a vocal over an instrumental with sidechain ducking (the beat dips under the words), presence EQ and a touch of reverb on the voice. Outputs a 24-bit WAV pre-master.

  • master_audio — the full chain with 2-pass loudnorm to an exact LUFS / true-peak target. A spatial option (immersive | subtle | none) controls the stereo image, and it reports the mono-sum drop so you can check mono compatibility.

  • export_dolby — encode to Dolby Digital Plus (E-AC-3) or Dolby Digital (AC-3).

Everything is deterministic and parameterized — same input + same settings → same master.


The mastering chain

master_audio runs this signal flow (industry-standard order, hip-hop-tuned):

input
  │  corrective EQ        high-pass 28 Hz · -2 dB @ 300 Hz (mud) · -1 dB @ 3 kHz (harsh)
  │                       +1.5 dB low shelf @ 90 Hz (warmth) · +2 dB air shelf @ 11 kHz
  │  glue compression     2:1, slow (20 ms / 200 ms), ~1–2 dB GR for cohesion
  │  multiband comp       3 bands (≤150 Hz / 150 Hz–4 kHz / ≥4 kHz) each lightly controlled
  │  saturation           gentle tanh soft-clip for harmonic warmth
  │  harmonic exciter     high-frequency sheen for clarity on small speakers
  │  stereo stage         none | subtle | immersive   (see below)
  │  limiter              driven peak limiter, ceiling -0.9 dBFS
  │  loudnorm (2-pass)    linear normalization to exact LUFS / true-peak target
output  → 320 kbps MP3

Stereo stages

spatial

What it does

none

Leaves the stereo image untouched.

subtle

Light overall widening (extrastereo).

immersive

Keeps the bass mono (solid, centered low end) while widening the highs (stereotools mid/side) and adding a subtle multi-tap air/depth. Biggest, most "premium" feel — at the cost of a few dB of level when summed to mono, which the tool reports back.


Install

# one-off, no install:
npx -y @ope-olatunji/audio-mastering-mcp

# or globally:
npm install -g @ope-olatunji/audio-mastering-mcp
audio-mastering-mcp

From source:

git clone https://github.com/ope-olatunji/audio-mastering-mcp.git
cd audio-mastering-mcp
npm install && npm run build
node dist/index.js

Use it in an MCP client

Claude Code (~/.claude.json or project .mcp.json) / Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "audio-mastering": {
      "command": "npx",
      "args": ["-y", "@ope-olatunji/audio-mastering-mcp"]
    }
  }
}

All file paths passed to the tools must be absolute.


Tools

analyze_loudness

Measure a file's loudness metrics.

Param

Type

Default

Notes

input

string

absolute path to a file

// → 
{ "integratedLufs": -11.7, "truePeakDb": -1.2, "lra": 1.1, "thresholdDb": -21.8 }

mix_vocal_over_beat

Combine a vocal and an instrumental into a pre-master WAV.

Param

Type

Default

Notes

beat

string

instrumental path

vocal

string

vocal path

output

string

output .wav path

vocalDelayMs

number

1200

how long the beat plays before the vocal enters

beatVolume

number

0.30

beat level under the vocal (lower = vocal forward)

vocalVolume

number

1.9

vocal level

The beat is sidechain-ducked under the vocal so the words always cut through.

master_audio

Run the full mastering chain to a target.

Param

Type

Default

Notes

input

string

pre-master / mix path

output

string

output .mp3 path

targetLufs

number

-10

integrated loudness target

truePeak

number

-1.5

true-peak ceiling (use ~-1.5 so MP3 stays ≤ -1.0)

spatial

"none" | "subtle" | "immersive"

"immersive"

stereo stage

bitrate

string

"320k"

MP3 bitrate

// → 
{
  "output": "/abs/track.mp3",
  "spatial": "immersive",
  "targetLufs": -10,
  "final": { "integratedLufs": -11.7, "truePeakDb": -1.2, "lra": 1.1 },
  "monoSumLufs": -15.3,
  "monoDropDb": 3.6        // how much level is lost when summed to mono
}

Why does it land at -11.7 when I asked for -10? Linear loudnorm will back off the gain rather than exceed your true-peak ceiling. Lower truePeak (e.g. -2.0) gives the encoder more headroom; the driven limiter is what lets it reach loud targets without clipping.

export_dolby

Encode to a Dolby codec.

Param

Type

Default

Notes

input

string

mastered stereo file

output

string

.eac3 or .mp4

codec

"eac3" | "ac3"

"eac3"

E-AC-3 (DD+) or AC-3 (DD)

bitrate

string

"384k"

channels

number

2

2 stereo · 6 basic 5.1 upmix


Loudness targets

Use case

Integrated LUFS

True peak

Hip-hop / trap / "loud"

-7 to -10

-1 dBTP

Pop / rock

-9 to -11

-1 dBTP

Streaming reference

-14

-1 dBTP

Podcast / spoken

-16

-1.5 dBTP

Streaming platforms normalize to ~-14 LUFS, so a louder master is turned down on playback — louder ≠ "wins." Pick a target for the vibe, keep true peak at or below -1 dBTP.


About "Dolby"

export_dolby produces channel-based Dolby codecs — the "Dolby" badge (E-AC-3 / AC-3). It is not object-based Dolby Atmos, and for a stereo music single it gives no sonic benefit over a good stereo master.

  • Want a bigger sound? Use master_audio with spatial: "immersive".

  • Want true Atmos (Apple Music Spatial Audio, etc.)? That requires Dolby's Atmos Renderer (built into Logic Pro) and your separate stems placed as 3D objects, exported as an ADM BWF master — a different pipeline that can't be done from ffmpeg.

The export_dolby tool description states this plainly so it's never oversold.


Requirements

  • Node.js ≥ 18

  • ffmpeg on your PATH, built with these filters/encoders (all standard in modern ffmpeg): acrossover, aexciter, asoftclip, stereotools, extrastereo, acompressor, alimiter, loudnorm, and the eac3 / ac3 encoders.

Override the binary with the FFMPEG_PATH environment variable. Check your build:

ffmpeg -hide_banner -filters  | grep -E 'acrossover|aexciter|stereotools|alimiter|loudnorm'
ffmpeg -hide_banner -encoders | grep -E 'eac3|ac3'

Troubleshooting

  • loudnorm JSON not found — the input file path is wrong or ffmpeg isn't on PATH. Use absolute paths; set FFMPEG_PATH if needed.

  • Master is quieter than targetLufs — the true-peak ceiling is capping the gain. Lower truePeak (more headroom) or accept that very dynamic material can't hit extreme loudness cleanly.

  • immersive sounds too wide / weak in mono — check monoDropDb in the result; if it's high (> ~4 dB), use spatial: "subtle" instead.

  • Output true peak slightly above target — MP3 encoding adds inter-sample peaks; target truePeak: -2.0 to land near -1.0 dBTP in the file.


License

MIT © Ope Olatunji

Available Tools

4 tools
analyze_loudnessA

Measure a track's integrated loudness (LUFS), true peak (dBTP), loudness range (LRA) and gating threshold. Call before/after mastering to verify levels against a target (hip-hop ~-9 to -10 LUFS, streaming -14, ceiling -1 dBTP).

ParametersJSON Schema
NameRequiredDescriptionDefault
inputYesabsolute path to an audio file

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It states the tool 'measures,' implying no side effects, but does not explicitly confirm it is non-destructive or mention any permissions or limitations such as file format support. More detail would improve transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first lists the measurements, the second provides usage guidance. It is front-loaded, concise, and every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does not explain what the tool returns, although it lists the metrics measured. The return format (e.g., object with fields) is missing, which could cause uncertainty despite the low parameter count.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'input' is described in the schema as 'absolute path to an audio file,' and schema coverage is 100%. The description adds no additional semantics like allowed formats or size constraints, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool measures specific loudness metrics (LUFS, dBTP, LRA, gating threshold), distinguishing it from sibling tools like export_dolby, master_audio, and mix_vocal_over_beat, which involve exporting, mastering, or mixing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance to call before or after mastering to verify levels against targets, with concrete examples like hip-hop (-9 to -10 LUFS) and streaming (-14 LUFS). It does not explicitly mention when not to use or alternatives, but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

export_dolbyA

Encode a track to a Dolby codec: 'eac3' = Dolby Digital Plus (E-AC-3), 'ac3' = Dolby Digital. IMPORTANT: these are channel-based Dolby codecs (the 'Dolby' badge), NOT object-based Dolby Atmos, and for a stereo music single give no sonic benefit over a good stereo master. True Atmos requires Dolby's Renderer (e.g. Logic Pro) and the separate stems. Default stereo at 48kHz; set channels=6 for a basic 5.1 upmix.

ParametersJSON Schema
NameRequiredDescriptionDefault
inputYesabsolute path to the mastered stereo file
outputYesoutput path, e.g. track.eac3 or track.mp4
codecNoeac3
bitrateNo384k
channelsNo2 = stereo; 6 = basic 5.1 upmix

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the encoding behavior, codec limitations, and default settings. However, it does not explicitly state side effects like file overwriting or permission requirements, though the operation is implied. Slight gap but still strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the main action and important caveat. It is concise but includes necessary details. Could be slightly more structured, but every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and moderate parameter coverage, the description is fairly complete. It covers purpose, usage guidelines, parameter nuances, and limitations. It could mention what happens if the output file exists, but overall provides sufficient context for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 60% description coverage; the description adds meaning by clarifying default stereo at 48kHz (not in schema) and explaining the channels parameter for 5.1 upmix. For codec, it lists the options. It adds value beyond schema but does not detail all parameters (e.g., bitrate not explained).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool encodes a track to Dolby codecs (eac3 or ac3), specifying the verb 'Encode' and resource 'track to a Dolby codec'. It also distinguishes from siblings by explicitly contrasting with Dolby Atmos, making its unique purpose clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: it warns that for a stereo music single there is no sonic benefit, and says True Atmos requires Dolby's Renderer and separate stems. It also suggests using channels=6 for a basic 5.1 upmix, giving clear when-to-use and when-not-to-use advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

master_audioA

Run a full professional mastering chain (corrective EQ -> glue compression -> 3-band multiband compression -> saturation -> harmonic exciter -> stereo stage -> driven limiter) with 2-pass loudnorm to hit an exact loudness/true-peak target. Outputs a 320kbps MP3. The 'spatial' option sets the stereo image: 'immersive' keeps the bass mono for a solid low end while widening the highs and adding subtle air for a bigger, more premium feel; 'subtle' adds light width; 'none' leaves the image as-is.

ParametersJSON Schema
NameRequiredDescriptionDefault
inputYesabsolute path to the pre-master (mix) audio
outputYesabsolute path for the mastered .mp3
targetLufsNointegrated loudness target in LUFS
truePeakNotrue-peak ceiling in dBTP (use ~-1.5 so MP3 encoding stays under -1.0)
spatialNoimmersive
bitrateNo320k

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full burden. It discloses the processing chain, output format, spatial options, and 2-pass loudnorm. It does not mention potential side effects or destructive nature, but these are inherent to mastering.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is detailed but front-loaded with the core mastering chain. Every sentence adds value, though it could be slightly more concise without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 params, no output schema), the description covers purpose, process, output, and parameter details comprehensively. It explains the spatial options in depth and specifies output format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All parameters have schema descriptions, but the tool description adds significant context, especially for the spatial parameter (explains each enum value) and the mastering chain. This enhances understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs a full professional mastering chain with specific processing steps (corrective EQ, compression, etc.) and outputs a 320kbps MP3. It distinguishes itself from siblings through its focus on the mastering process.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for mastering audio to hit loudness/true-peak targets, with clear output format. It does not explicitly state when not to use or alternatives, but the sibling tools context suggests it's for final mastering.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mix_vocal_over_beatA

Mix a vocal over an instrumental with sidechain ducking (the beat dips under the vocal so words cut through), plus presence EQ + light reverb on the voice and the beat pulled underneath. Outputs a 24-bit WAV pre-master that you then feed to master_audio.

ParametersJSON Schema
NameRequiredDescriptionDefault
beatYesabsolute path to the instrumental
vocalYesabsolute path to the vocal
outputYesabsolute path for the .wav pre-master
vocalDelayMsNohow long the beat plays before the vocal enters
beatVolumeNobeat level under the vocal (lower = vocal more forward)
vocalVolumeNo

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden and discloses key behaviors: sidechain ducking, EQ, reverb, and output format. It does not mention destructive nature or requirements, but covers the core processing well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (two sentences) and front-loaded with the main action, followed by output format and downstream tool. Every sentence adds meaningful information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of audio mixing and lack of output schema, the description adequately covers the tool's purpose, effects, output format, and linkage to master_audio. It could mention the file format expectations for inputs, but overall complete enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds value beyond the input schema by explaining the overall processing context (sidechain, EQ, reverb). Schema itself covers 83% of parameters with descriptions; the tool description complements it by showing how parameters relate to the audio effect.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: mixing vocal over an instrumental with specific audio processing effects (sidechain ducking, presence EQ, light reverb, beat pulled underneath). It distinguishes from siblings by explicitly mentioning the output is a pre-master for master_audio.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates when to use this tool (before master_audio) and gives a brief context of the processing chain. However, it does not explicitly state when not to use this tool versus alternatives, though the sibling list suggests different stages.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedanalyze_loudness
    • First observedexport_dolby
    • First observedmaster_audio
    • First observedmix_vocal_over_beat

TDQS

A4.3/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: analyze_loudness for measurement, export_dolby for encoding, master_audio for full mastering, mix_vocal_over_beat for vocal mixing. No overlap.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern (analyze_loudness, export_dolby, master_audio, mix_vocal_over_beat), making the set predictable.

Tool Count5/5

Four tools is well-scoped for an audio mastering server, covering essential functions without being too few or too many.

Completeness4/5

The tool surface covers analysis, mixing, mastering, and export. A minor gap is the lack of direct raw WAV export without mastering, but mix_vocal_over_beat provides a pre-master WAV.

Maintenance

ActivityStale
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • -
    license
    B
    quality
    Not graded
    maintenance
    An MCP server designed to work with FFmpeg for media processing tasks, offering enhanced performance and secure communication for handling media processing requests.
    2
    142 npm
    15
    -
  • A
    license
    A
    quality
    A
    maintenance
    An interactive digital audio workstation as an MCP server, enabling music production with a channel rack, piano roll, mixer, effects, automation, microphone recording, and offline WAV rendering.
    26
    27 npm
    1
    MIT