mcp_sound_engineer
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp_sound_engineer
An MCP server that measures audio and decides like a mix/master engineer, returning a DAW-neutral action plan.
It does not control any DAW. It measures and decides; a separate adapter applies the plan. That
adapter is code in this repository (adapter/), not an LLM improvising calls:
┌───────────────────────┐ facts + answers + recipe ┌──────────────────────────┐
│ mcp_sound_engineer │ ───────────────────────────► │ adapter/ (this repo) │
│ measure → judge │ (neutral JSON) │ recipe → mcp_logic calls│
└───────────────────────┘ └────────────┬─────────────┘
numpy + Jev │ JSON-RPC
┌─────────────▼─────────────┐
│ mcp_logic (DAW MCP) │
│ Logic Pro │
└───────────────────────────┘Two hats: mixing (N stems: balance, masking, corrective EQ) and mastering (one stereo file: send-back gates, dynamics, limiter, playback-normalization reference, dither).
1. Requirements
What | Why |
macOS or Linux, Python 3.9+ | Runs the server; the venv script assumes a POSIX shell |
| The start script creates a local |
Network access | Only for Jev decisions; measurement is fully offline |
A Jev API key | See §2; |
~20 MB disk | numpy plus the venv |
No ffmpeg, no libsndfile, no system packages. WAV is read with the standard library; FLAC/OGG/AIFF
need the optional soundfile extra.
Related MCP server: ableton-auto-mix-mcp
2. Getting a Jev key
Jev is a System One decision model by TypeSafe AI. It answers choice / score / noul with
calibrated probabilities instead of prose — that is why the output is machine-actionable.
Open https://jevtypesafeai.com/pricing#get-key and create an account.
Create a key. Two kinds exist and they hit different endpoints:
Key looks like
Endpoint
Notes
jv_live_…https://jevtypesafeai.com/api/v1/decideHosted playground/reseller
apikey_…https://api.typesafe.ai/v1/systemoneOfficial TypeSafe API (default here)
Put it in
.env:
# required: the key from step 2
JEV_API_KEY=apikey_...
# optional: override the endpoint chosen from the key prefix
JEV_ENDPOINT=https://api.typesafe.ai/v1/systemone
# optional: model id
JEV_MODEL=jev-latest.env is git-ignored. The server re-reads it on every decision, so you can rotate the key without
restarting.
A key from one endpoint does not work on the other: a
jv_live_key againstapi.typesafe.aireturns401, and vice versa. Ifjudge_*fails with an auth error, check which service issued the key. Without a key the server still starts,analyze_*works, and everyjudge_*call returns a clear error.
3. Install and run
cd mcp_sound_engineer
./start-sound-engineer-mcp.sh # creates .venv, installs deps, starts HTTP on :8766Command | What it does |
| HTTP bridge on |
| Same, another port |
| JSON-RPC over stdin/stdout (MCP clients that spawn it) |
| Lifecycle via |
| Offline smoke test; does not need |
Register it in any MCP client next to the DAW MCP (mcp_logic) — they are separate servers. The
translation from recipe to calls is adapter/, a client of mcp_logic, not another server:
{"mcpServers": {
"engineer": {"command": "/abs/path/mcp_sound_engineer/start-sound-engineer-mcp.sh", "args": ["--stdio"]}
}}4. Tools
Tool | Input | Returns |
| one stereo file | LUFS, true peak, LRA, crest, phase correlation, mono fold-down loss, 6 bands, sibilance, centroid, measured lossy cutoff, clipping and flat-topped frames; mono/stereo/5.1 layouts |
| N files | per-stem loudness, peak, bands, sibilance, low-band correlation, time-weighted pairwise overlap while both stems are active (a spectral-crowding proxy, not perceptual masking), and stem gates (buried vocal, outlier element, mono bass) |
| path + window | per-window LUFS/bands/correlation, deviation from the median (informational), and a partial final window when the tail is ≥5 s |
| path | a commercial reference's band balance and sibilance, to feed |
| recipe | adapter-side contract check: caps, schema, action ids, |
| recipe + before/after files (optional stem lists) | per-action |
| path, platform, optional |
|
| stem paths |
|
| — | rules version, Jev status, platforms |
Every tool advertises annotations.readOnlyHint: true: none edits audio or writes files, so a
client may call them without a confirmation prompt.
5. The rules, and where they live
Sources: the mastering-engineer methodology (send-back gates, ten-stage chain, parameter ranges) and a third-party 2026 loudness cheat sheet that has not been checked against primary platform docs.
Everything numeric lives in server/rules.py, together with the question schemas:
one source of truth for both the numbers and the answer keys.
Rule | Value | In code | Behaviour |
Phase correlation | < +0.3 |
| measured → |
Missing gate input | any of phase, mono fold-down loss, clipping/flat-top count, duration, sample rate, LRA/TP/LUFS, bandwidth, or the measured bands behind a requested correction |
| not measured → |
Clipping that blocks mastering | ≥ 500 frames and ≥ 0.01 % |
| measured → |
True peak above full scale | > 0 dBTP |
| measured → |
Already a finished master | LRA < 4 and TP > −1 and LUFS > −12 |
| measured → |
Corrective EQ per point | score 2–10 maps to 0–4 dB; ≤ 3 dB applied, bounded by the measured excess over the reference |
| only the extreme score exceeds the cap → |
Cumulative corrective EQ | ≤ 6 dB |
| includes the sibilance cut |
Masking (mix) | score 2–10 maps to a 0–3 dB cut, below 2.5 no cut |
| frequency and stem pair come from the time-weighted co-activity pairs; stems that never sound together get no bell; sub/bass-only overlap emits no bus bell; no measurement means no invented frequency; |
Upward expansion | not offered |
| over-compressed material is an upstream problem; no action is emitted and the warning says so |
Total gain reduction | ≤ 6 dB (source range 6–8) |
| compressor + limiter summing over budget → |
Mono compatibility | fold-down loss < 6 dB |
| measured → |
Gain staging (mix) | every stem toward −18 LUFS |
| deterministic faders, ±6 dB max; a capped move or unmeasured loudness is warned |
Phase before EQ (mix) | correlation < +0.3 |
|
|
Confidence | < 0.5, or absent |
|
|
Broadband compression | 1.5–3:1, 10–30 ms, 1–3 dB GR |
| emitted on the master bus |
Dynamics amount | abstract score 2–10 |
| linear 2→1 dB, 6→2 dB, 10→3 dB; outside the scale clamps, never interpreted as dB |
De-esser | after compression |
| emitted after the compressor |
Limiter | GR = max(0, tp + input_gain − ceiling); ceiling from the destination |
| input gain = min(loudness request, peak budget); |
Pre-limiter trim | ≤ 3 dB; more than 7 dB over the ceiling → |
| a peak that 4 dB GR + 3 dB input trim cannot fix is not a mastering problem |
Dither | only when the destination needs fewer bits than the source |
| none for streaming; TPDF for CD/podcast only if reducing |
Playback normalization | Spotify −14, Apple −16, … |
| informational; never a delivery target |
Unknown destination | — |
| raises, no silent fallback |
Reference curve | measured from a real track when |
| default six-band linear sum = 1.0; |
Correlation drop after the chain | > 0.15 |
| warning when |
Sibilance | 5–9 kHz relative to full-band energy |
| measured as |
Noise floor | > −50 dB; minor between −60 and −50 |
| measured in silence only; > −50 → |
Lossy source | measured cliff > 20 dB in adjacent 1 kHz bands above 10 kHz, up to Nyquist |
| measured (suspected flag or measured drop) → |
| vocabulary only in the decision model |
| ❌ not emitted by |
The decision model never gates. It scores and chooses treatments; every refusal is measured.
Asking it "should this be sent back?" produced a global yes/no that contradicted its own
component scores (0.81 refuse, yet low_end 1.46 and high_mid 1.68 — both "slight").
How to know a rule is real
./start-sound-engineer-mcp.sh --test # 348 tests: smoke + rules + jev + analysis + adapter + looptests/test_rules.py asserts behaviour, plus the limiter's two-constraint arithmetic:
every balance label lowers the offender, and a fader points at a real exported stem;
a corrective request above 3 dB returns
send_backinstead of a clamped band, and the cumulative cap counts the sibilance cut (7.5 dB →send_back, no zero-gain bell);corrective bells use Q 4–8;
60 clipped frames in 10 s do not send back, 5000 do, and 5 frames in 1 s do not;
a missing gate input is
unmeasured:<field>and a terminalsend_back, never a healthy default;the limiter's input gain is min(requested loudness, peak budget), and the peak-only default never invents input gain;
the abstract dynamics score maps explicitly onto 1–3 dB GR (
map_score);dithernever appears for a streaming destination;the two recipe builders reject any answer key missing from their schema (this is the test that catches a
low_end/low_midmismatch);an unknown destination or unknown action target raises instead of falling back.
tests/test_analysis.py uses signals whose correct value is known: a 997 Hz sine at −20 dBFS must
read −20 LUFS ±1, a 440 Hz sine must show 3.01 dB crest, inverted channels must correlate at −1.0,
and trailing silence must not change integrated loudness by more than 1 LU (BS.1770 gating).
When you change a rule, break it on purpose first. If the suite stays green, the test is decoration.
Adding a rule
The number →
GATE(a cap) orPLATFORMS/REFERENCE_CURVE(a target).The judgement →
MASTER_QUESTIONS/MIX_QUESTIONSin the same file.noulonly for something that cannot be measured;scorefor magnitudes;choicefor treatments.The action →
build_master_recipe/build_mix_recipe, emitting_action(...). Enforce the cap in code; never trust the model to respect it.
6. The recipe contract
Recipes are ordered arrays of action primitives; no plugin, vendor or DAW name appears.
Full schema: docs/RECIPE.md (currently 2.2.0).
[
{"id": "eq-high-pass:master", "action": "eq.high_pass", "target": "master", "schema": "2.2.0", "freq_hz": 25, "slope_db_oct": 12},
{"id": "eq-bell:master:bass", "action": "eq.bell", "target": "master", "schema": "2.2.0", "freq_hz": 150, "gain_db": -2.0, "q": 4.0, "role": "corrective",
"expect": {"metric": "spectral.bands_db_rel.bass", "delta_db": -2.0, "tolerance_db": 1.5}},
{"id": "limiter:master", "action": "limiter", "target": "master", "schema": "2.2.0", "ceiling_dbtp": -1.0, "input_gain_db": 0.0, "expected_gain_reduction_db": 2.0,
"expect": {"metric": "loudness.true_peak_dbtp", "max": -1.0, "tolerance_db": 0.1}},
{"id": "send-back:master", "action": "send_back", "target": "master", "schema": "2.2.0", "reasons": ["already_mastered:measured"]}
]expect is the closing measurement, not a promise: verify_recipe compares before/after and
returns unmeasured when the metric is absent. A post-bounce check can therefore fail honestly
instead of assuming the action worked.
Applying it: adapter/
The recipe is DAW-neutral; adapter/ translates it into calls that mcp_logic HEAD
b42cdd37 verifies (pinned in adapter/mcp_logic_contract.py). Anything outside that surface
is manual and emits no call at all. Full contract, loop semantics and safety notes:
docs/ADAPTER.md.
python -m adapter.cli --recipe recipe.json --project /path/Session.logicx \
--tracks "vocal=3:Lead Vocal,01_bass.wav=2:Bass" --master "Stereo Out" \
--inventory /tmp/inventory.json # dry run against a saved inventory
# --fetch-inventory reads it live (read-only); --apply always re-reads it liveA --tracks key may be a role or an exported basename. When a recipe action carries stem,
the basename wins over the role key; an explicit target: "stem" never falls back to a role.
The Stereo Out strip has no Arrange index: it is addressed as strip: "output", and an
--master index (0:Stereo Out) is accepted only as informational.
Action | Status | What it emits |
| needs_calibration |
|
| ready |
|
| ready |
|
| ready | same insert, then |
| manual | Low Cut is observed-only; slope is a host popup |
| manual | insert-only in this surface: no verified ratio/attack/release; inserting DSP you cannot configure is an unverified side effect |
| manual | not in the insert allowlist and no verified-writable parameter |
| manual | Gain is insert-only; |
| manual | no verified surface; the step carries the manual instruction |
| terminal | nothing is applied |
Unsupported actions are reported, never improvised. Every action in rules.ACTIONS has a declared
capability (ready, manual or terminal); a manual step carries apply_by: "human" and the
reason, emits no MCP call, and blocks the loop from claiming delivery (exit 2). A new action
defaults to manual until the table is updated and tested. The matrix is enforced by
tests/test_adapter.py::test_capability_matrix_is_honest and
::test_manual_actions_emit_no_calls_and_explain_why.
Every plugin call carries mode: duplicate_applyback and project_expected_path;
insert_verified also carries expected_name. Mixer calls are the two-field
{"track", "value"} form. set_eq_band_verified never carries expected_name, and the adapter
never emits Q-Factor, outputCeiling or phaseInvert.
--apply is off by default. A call is only accepted when the Honest Contract envelope is
State A (success, verified, state: "A", and hc_schema: 2 for logic_plugins.*). State B
(unverified) and State C (error / write_attempted) stop the run; there are no write retries
and no rollback. After an insert the adapter refreshes the live inventory and binds writes to
the observed plugin_insert_ref (track) or the observed slot on strip: "output" (master).
A pre-existing track EQ needs --overwrite-eq. A pre-existing master EQ is never reused or
overwritten: its state is unreadable and the output strip emits no refs.
Closing the loop: adapter/loop.py
adapter/loop.py exports a master bounce, measures it, compares it, and iterates only on
verified Channel EQ gains:
python -m adapter.loop --recipe recipe.json --project /path/Session.logicx \
--tracks "vocal=3:Lead Vocal" --master "Stereo Out" \
--output-root /path/exports --applyIt is a dry run without --apply: no directories, no exports, no writes, no report. With
--apply it builds output_root/<run-id>/{baseline,stage,iter-1,iter-2} (stage only when
faders/pan/shelves exist), exports with logic_project.export_plan + export_run, measures
in-process, and calls logic_audio.compare_spectra with spectral_shape. Every artifact is
hashed locally and its compare_spectra fingerprint must match, or the loop stops.
The effect window of a bell is the FWHM approximation |log2(center/freq)| <= 0.72/q.
G_new = G_cur + clamp(deviation, ±--max-correction-db) and only a track band is corrected,
read back to ±0.1 dB. Corrections are refused beyond 3 dB per point, 6 dB cumulative, or the
--max-cumulative-correction-db cap. Overlapping bells, manual dynamics, disabled bands and
master EQ are never auto-corrected. A tracked bell that lands but cannot be measured stops as
readback_confirmed; the loop does not pretend the spectrum confirmed it.
Because the limiter, compressor and high-pass are manual, a generated master recipe normally
ends with exit 2 (manual_delivery or partial_manual). The loop can verify EQ transfer; it
cannot declare final loudness/true-peak delivery. Exit codes: 0 verified convergence,
static-only, readback-confirmed, terminal recipe or a clean dry run; 2 honest stop with manual
work, a limit or low trust; 1 failure. The full stop-reason matrix is in
docs/ADAPTER.md.
7. What has and has not been verified
Measured on 24 real music clips (8 tracks × 3 versions: original, +3.4 dB at 60–250 Hz, +5.3 dB at 6–16 kHz):
Check | Result |
Direction on +5.3 dB of added highs | 8/8 |
Direction on +3.4 dB of added lows | 5/8 (both failures were scale saturation) |
Spearman(measured tilt, "bright") | +0.77 |
Stability across runs | ±1 point |
End-to-end on a full 284 s track | ≈6 s per call (numpy-only: K-weighting + 4× true peak) |
Not verified: no human labels, one repetition per clip, synthetic perturbations. It measures sensitivity to a known change, not agreement with a trained ear.
8. Status
0.9.1 (rules 2.3.0). Measurement, gates, sections, references, the recipe contract and a
closed apply → export → measure → iterate loop are in place, with CI on 3.9/3.11/3.12. What is
still missing is tracked in docs/LIMITS.md:
the adapter emits only what mcp_logic verifies — volume/pan and Channel EQ (a verified-empty insert plus
Frequency/Gain/Q). Limiter, compressor, polarity, high-pass, de-esser, dither and stereo imaging are manual;the loop closes EQ transfer, not loudness delivery — with a manual limiter/compressor it stops honestly (exit
2) instead of compensating with EQ;master Channel EQ is advisory — its band state cannot be read back, so it is applied once and never auto-corrected;
confidence policy — answers below a threshold still produce a recipe instead of a refusal;
no human-labelled evaluation — sensitivity is measured, agreement with an engineer is not.
License
MIT.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
AI mixing and mastering: analyze your mixes, run DSP autofix, render stems, and master tracks.
Compose, mix, master and export in Logic Pro, REAPER or Ableton Live by talking to an AI engineer.
AI music production assistant — audio profiling, AI mixing sessions, and service inquiries.
Audio analysis and production jobs: BPM, key, fingerprint, tags, stems, cleanup, mastering.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAnalyzes audio files to extract exact, reproducible measurements like loudness, tempo, key, spectral balance, and clipping for LLM-based DAW control.-
- AlicenseAqualityCmaintenanceStyle-aware auto-mixing and mastering for Ableton Live, providing tools for analysis, preview rendering, and release checks.1059 PyPI3MIT

Echoteka MCPofficial
AlicenseAqualityCmaintenanceEnables MCP clients to measure a track's loudness and peak levels, strip artifacts left by AI generators, compare mastering presets, and master single tracks or batches to streaming targets via a hosted remote server or a local stdio bridge. Tracks are supplied as public HTTPS links, with analysis, cleanup and previews free and full masters limited by a daily free quota or credits.9MIT- AlicenseCqualityBmaintenanceEnables AI clients such as Claude to compose, arrange, sound-design and mix inside Ableton Live, with loudness/true-peak measurements from real bounces and reference matching. It also lets users summarise, lint, diff and export Live Sets offline while Live is closed, with every tool marked read-only or destructive and destructive batches run as a single undo step.148MIT