# REW MCP Server

[![CI](https://github.com/manuaero/rew-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/manuaero/rew-mcp-server/actions/workflows/ci.yml)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
[![Server code: MIT](https://img.shields.io/badge/server%20code-MIT-green)](LICENSE)

Control [Room EQ Wizard](https://www.roomeqwizard.com/) from Codex, Claude Desktop,
or another MCP client. Measure, inspect responses, work with EQ and alignment,
configure audio and simulation, and export data through REW's local HTTP API.

The bridge discovers REW's API instead of maintaining a fixed list of wrappers.
The included **REW 5.40 Beta 148 / API 0.9.9** snapshot contains **608 operations
across 384 paths**. All of those operations can be discovered and called through
16 compact MCP tools. Optional `--all-tools` mode adds an individual tool for
each operation: 624 tools for that snapshot. Live coverage follows the connected
REW version.

```mermaid
flowchart LR
    Client[Codex / Claude / MCP client] <-->|MCP over stdio| Bridge[REW MCP Server]
    Bridge <-->|HTTP on loopback| REW[Room EQ Wizard 5.40+]
    REW -->|doc.json| Catalog[Live API catalog]
    Catalog --> Bridge
```

## What it can do

| Area | Capabilities exposed by REW |
| --- | --- |
| Measurements | Sweeps, summaries, UUID selection, frequency/impulse responses, group delay, distortion, RT60, windows, smoothing, arithmetic, and groups |
| EQ and alignment | Targets, house curves, filters, equaliser models, optimization, predicted responses, phase/delay alignment, and aligned sums |
| Audio and generator | Java/ASIO routing, channels, sample rates, input levels, signal configuration, level, frequency, and play/stop |
| Live analysis | SPL meters/logger, RTA, stepped measurements, and available progress endpoints |
| Room simulator | Dimensions, surfaces, sources, positions, configuration, and responses |
| Files and application | MDAT save/load, response imports, supported REW export commands, graphs, image capture, warnings, and errors |

The bridge also decodes REW's Base64 float arrays, reconstructs frequency/time
coordinates, calculates response statistics, exports CSV/JSON, writes house
curves, and paginates large results without silently truncating them.

**Requirements and limits:** Python 3.12+, REW 5.40+ with its API enabled, and an
MCP client with stdio support. Automated sweep measurements require **REW Pro**.
GUI-only features are accessible only where REW provides an API operation.
Callbacks require a receiver supplied by the integrating application. The
bridge runs on the same computer as REW and does not start audio at startup.

## Quick start

Clone the repository:

```sh
git clone https://github.com/manuaero/rew-mcp-server.git
cd rew-mcp-server
```

### Windows

Install [Python 3.12+](https://www.python.org/downloads/) and an API-enabled REW
version from the [official REW downloads](https://www.roomeqwizard.com/beta.html).
Then run in PowerShell:

```powershell
.\scripts\Setup.ps1 -RegisterCodex
.\scripts\Start-REW.ps1
.\.venv\Scripts\python.exe -m rew_mcp.server --check
```

`-RegisterCodex` is optional; it requires the Codex CLI. Supply
`-Python C:\path\to\python.exe` or `-RewPath C:\path\to\roomeqwizard.exe` when
using non-default installations. The setup script installs this bridge; REW is
installed separately.

### macOS and Linux

```sh
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
```

Start REW with its API enabled. On macOS:

```sh
open -a REW --args -api
```

On Linux, launch your REW executable with `-api`. Verify the connection:

```sh
.venv/bin/python -m rew_mcp.server --check
```

### Connect your MCP client

For Codex, use the absolute path to the virtual environment's Python:

```sh
codex mcp add rew -- /absolute/path/rew-mcp-server/.venv/bin/python -m rew_mcp.server
```

For Windows, the interpreter is `.venv\Scripts\python.exe`. For Claude Desktop
and other clients, start with [examples/mcp-config.json](examples/mcp-config.json)
and replace the example paths. Restart the MCP connection after registration.

See [installation](docs/installation.md) and
[client configuration](docs/client-configuration.md) for complete instructions.

## Try it

- "Check the REW connection and list my measurements."
- "Analyze this measurement between 20 and 200 Hz."
- "Read the current audio routing and sweep settings."
- "Find the available equaliser models and target settings."
- "Inspect the alignment tool operations for my main and subwoofer."
- "Export this frequency response as CSV."

The normal workflow is **search → describe → call**:

```json
{"name":"rew_search_api","arguments":{"search":"target","tag":"eq"}}
```

Use the returned operation ID with `rew_describe_api` to inspect its exact
parameters, then call `rew_call_api`. `rew_request` also accepts a documented
method/path directly. Use measurement UUIDs because measurement indices change.

Before playback, inspect actual routing, levels, and protection settings. A
successful HTTP 202 means accepted, not completed. The bridge never
automatically retries a mutation after a timeout.

## Documentation

| Guide | Contents |
| --- | --- |
| [Installation](docs/installation.md) | Windows/macOS/Linux setup, REW startup, headless testing, upgrades, and removal |
| [Client configuration](docs/client-configuration.md) | Codex, Claude Desktop, other stdio clients, paths, timeouts, and environment variables |
| [Tool reference](docs/tools.md) | All 16 MCP tools and their generated input schemas |
| [API catalog](docs/api-catalog.md) | Every operation in the bundled REW snapshot, organized by category |
| [Workflows](docs/workflows.md) | Response analysis, EQ, alignment, import/export, batching, and progress handling |
| [Architecture](docs/architecture.md) | API discovery, validation, transport, data encoding, lifecycle, and project layout |
| [Troubleshooting](docs/troubleshooting.md) | Connection, licensing, parameter, async, file, and audio issues |
| [Contributing](CONTRIBUTING.md) | Development, tests, documentation generation, and pull requests |
| [Security model](SECURITY.md) | Local trust boundary, data handling, and reporting issues |
| [Changelog](CHANGELOG.md) | Version history |

## Development and tests

```sh
python -m pip install -e '.[dev]'
python -m pytest -q
python -m ruff check src tests scripts
python -m ruff format --check src tests scripts
python scripts/generate_docs.py --check
```

The default tests do not need REW. They cover the full bundled API catalog,
validation, array decoding, analysis, offline behavior, timeouts, stale progress,
file handling, workflows, and actual MCP stdio sessions in both tool modes.

The opt-in live smoke test uses a synthetic measurement and plays no audio:

```sh
python scripts/live_smoke.py
```

It temporarily adds and removes its own measurement. It does not verify physical
audio I/O, Pro-only sweeps, or every mutation. CI runs the offline tests and builds
the package; it does not run the live test.

## Acknowledgments and license

Inspired by [KevinMeinon/rew-mcp-server](https://github.com/kevinmeinon/rew-mcp-server).
This is an independent implementation using the official
[MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x).
Room EQ Wizard is developed by John Mulcahy; see the
[REW API documentation](https://www.roomeqwizard.com/help/help/html/api.html).

The server code is [MIT licensed](LICENSE). The bundled REW API specification
retains its source metadata and [REW EULA](https://www.roomeqwizard.com/eula.html)
reference; it is not relicensed as part of this server. This project does not
include REW binaries and is not an official REW product.