Audio Calibration MCP

Audio Calibration MCP

[Audio Calibration MCP calibration-bunny logo]

Audio Calibration MCP is a local-first, cross-platform Model Context Protocol server for Room EQ Wizard (REW). It guides acoustic measurement, speaker and room calibration, subwoofer and crossover analysis, conservative EQ, DSP deployment, and measured verification for general, powered-speaker, car, and laptop audio systems.

You use it from an AI assistant such as Codex, Claude Code, or Cursor on the same computer as REW. MCP is the connection that lets the assistant call these tools; this project is not a separate calibration app. REW does the measuring, and your DSP or receiver applies the changes it supports.

This project does not promise universally “perfect” sound. REW can measure an acoustic system; it cannot infer listener preference, microphone placement, or a speaker's safe output capability without evidence. The MCP reports missing data and keeps preference separate from engineering calculations.

[CI] [CodeQL] [Release] [License: MIT] [Buy Me a Coffee]

Start here

New to MCP? Follow the written walkthrough. It covers what you need, how to install and connect the tools, and how to analyse your first REW measurement. You can begin with measurements you already have.

• Install with Codex, Claude Code, or Cursor
• Before and after: the measured example and its limits
• Troubleshooting

The MCP is free and open source. Your chosen assistant has its own account and billing requirements. Automated REW sweeps through the API require a REW Pro license; reading existing measurements does not require automated sweep control. See REW's API documentation.

Choose the right audio MCP

The projects share measurement discipline, but this MCP deliberately stays hardware-neutral; EvoBurrow owns the A1 and AVR-specific safety boundary.

Measured laptop example — before and after

[REW frequency-response comparison of factory laptop speakers and the JamesDSP-tuned preset]

This is measured evidence from four repeated REW sweeps per state, averaged with 1/12-octave smoothing. Factory is amber and the cut-only JamesDSP preset is cyan. The shaded area below 500 Hz marks the protection-limited bass region where no boost was applied. The plot preserves measured SPL; preference was assessed in a separate level-matched listening comparison. Device, microphone, and preset identifiers are intentionally removed from the public artifact.

See the example explained for what this plot shows, what it does not establish, and how to compare changes on your own system.

Compatibility

Install

Follow the installation guide for release downloads, absolute file paths, and the configuration for your assistant. Codex uses config.toml; the repository's .mcp.json is not automatically loaded by the Codex CLI. The guide gives an explicit registration command.

For a source checkout:

npm ci --ignore-scriptsnpm run buildnpm testnpm run validate:release

The checked-in MCP configuration starts the self-contained dist/server.mjs. The packaged CLI is also bundled, and the published artifact declares zero runtime npm dependencies. Third-party build inputs are exact-pinned and installed with lifecycle scripts disabled. Run rew_install_discover to locate REW through a user override, the AUDIO_REW_EXECUTABLE environment variable, PATH, and conventional Windows, macOS, or Linux locations. If discovery fails, pass the absolute executable path (or REW.app on macOS) to that tool or rew_launch_plan. Starting REW requires the matching rew_launch_execute confirmation. Startup is verified against the API on http://127.0.0.1:4735; override AUDIO_REW_URL only for a trusted local network endpoint. REW's API still must be enabled in REW itself.

Guided workflow

The beginner walkthrough uses ordinary prompts and explains what to expect. The steps below are the tool sequence for users who want to work directly with the MCP interface.

1. Run audio_doctor. If REW is offline, use rew_install_discover, then the confirmed rew_launch_plan/rew_launch_execute pair. Continue with rew_capability_negotiate and audio_guided_session_plan.
2. Inventory the host, REW, microphone calibration, output route, and DSP state.
3. Create a protected repeated-session plan. Audible execution requires fresh microphone-placement, area-clear, and route/safety confirmation.
4. Save separate raw traces, then run quality, dual-resolution, direct/late, crossover, distortion/compression, and human-listening analyses.
5. Prefer placement, polarity, timing, crossover, and stable cut-first EQ.
6. Apply only a hash-bound confirmed plan with backup and rollback.
7. Re-measure at matched level. Start audio_post_eq_verification, then poll audio_job_status; the verifier derives level difference from the traces. Predicted response and caller-claimed level matching are never acceptance evidence.
8. Use randomized, level-matched A/B or ABX for preference/discrimination. On JamesDSP, jamesdsp_ab_plan plus its presentation and restore executors switch presets and host volume transactionally without revealing assignments.

Analysis views

Reports preserve the source trace and display native unsmoothed data, derived engineering resolution, 1/48-octave structure, adaptive modal-to-perceptual smoothing, and ERB/perceptual views. Filters are eligible only when features are stable across repetitions and held-out data. Narrow/spatial nulls are not boosted.

audio_report_plan can also accept two to four repeated comparison groups. It averages each state, preserves ±1 SD, calculates the measured level difference, and exports Markdown, HTML, JSON, and a standalone labeled SVG suitable for a README. Missing SNR rejects the quality gate by default; exploratory callers must explicitly opt out with requireSnr: false.

Privacy

There is no telemetry. Local sessions may contain usernames, absolute paths, device names, room coordinates, microphone hashes, and preset fingerprints. Never publish measurements/, sessions/, backups/, profiles/, reports/, or filters/ directly. Use the redacted support-artifact tools and review the result before sharing it.

Development and validation

npm test is hardware-independent. npm run coverage exercises deterministic DSP and safety fixtures. npm run validate:release checks manifests, metadata, the bundled server, and package contents. Real-system smoke tests are opt-in and must never run in ordinary CI.

REW requests are bounded to four concurrent calls by default. Set AUDIO_REW_MAX_CONCURRENCY from 1–8 only when the local REW instance has been validated at that concurrency.

See SECURITY.md, CONTRIBUTING.md, and CHANGELOG.md. Licensed under the MIT License.

Measurement-science laboratory modules

Bounded tools cover GUM-style uncertainty budgets and Monte Carlo propagation, bootstrap repeatability, complex-transfer coherence and phase confidence, ISO-3382-aligned room screening, exploratory polar/directivity scans, clean-output ladders, held-out-seat complex multi-source optimization, regularized FIR proposals, controlled listening trials, immersive/SOFA metadata preflight, and reference-corpus auditing.

Screening, inspired, and standards-aligned never mean certified conformity. ISO, IEC, ANSI/CTA, AES, and ITU conformity requires the complete current normative document, prescribed setup and processing, calibrated instrumentation, and traceable evidence. Optimization and FIR outputs remain proposals until protected, level-matched hardware remeasurement accepts them.

Curated external datasets

audio_dataset_catalog exposes reviewed metadata for selected SADIE II, FLAIR, MeshRIR, and RAVes artifacts without downloading them. Dataset acquisition uses a hash-bound plan/execute pair, requires license acknowledgement, enforces an exact byte ceiling, accepts only pinned Zenodo HTTPS URLs, refuses overwrites, checks the upstream checksum, calculates SHA-256, and writes a provenance receipt under the workspace datasets/ directory.

Remote entries and checksum-verified downloads are not automatically scientific validation. Readiness is calculated per domain and requires parsed, method-compatible references from at least two independent institutions with justified tolerances.

Laptop calibration

Laptop speakers remain fully supported, but this is the least general workflow and is intentionally documented last. Laptop mode starts at 120 Hz and -30 dBFS by default. Stop immediately on an unexpected route, silence, clipping, limiter activity, rattling, or distress.

Support the project

Audio Calibration MCP is free and open source. If it saves you time or improves your system, you can buy daredoole a coffee.