# MCP RIR

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-server-orange.svg)](https://modelcontextprotocol.io/)

Room impulse responses from a plain description, via
[pyroomacoustics](https://github.com/LCAV/pyroomacoustics).

An MCP server that lets any compatible agent generate an IR from natural
language and write it where you want. Describe a space in any language and the
calling model turns it into room dimensions, an absorption coefficient and
mic/source positions.

Useful for matching a room you no longer have access to (dry foley or dialogue
recorded on location, with no IR captured at the time), and for building
reverbs that are realistic, impossible, or somewhere between.

## Example

> "a stairwell, mic near the wall, quite reverberant, put it in my samples
> folder"

```
2.4 × 4.8 × 11.2 m · absorption 0.06 (wet) · mic near wall · source near wall
2.33 s stereo, 48000 Hz
/Users/you/Music/samples/medium_near_wall_wet_b7b2.wav
```

The result loads into any convolution reverb.

Anything left unspecified is randomised. Values you do supply are used as
given, but exact mic placement and per-wall absorption are redrawn on every
call, so the same numbers twice produce a different take. Call again to reroll.

## Setup

Requires [uv](https://docs.astral.sh/uv/getting-started/installation/). Add the
following to your MCP client configuration
(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS)
and restart the client:

```json
{
  "mcpServers": {
    "rir": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/tbimbato/MCP_RiR", "mcp-rir"],
      "env": {
        "RIR_OUTPUT_DIR": "~/Music/IRs"
      }
    }
  }
}
```

The first launch takes a minute while pyroomacoustics is fetched.

`RIR_OUTPUT_DIR` sets the default destination. Without it, files land in
`~/RIR-MCP/`. A destination can also be given per request ("put it in my
samples folder", "call it hallway.wav").

## The tool

`generate_room_ir`. Every argument is optional.

| argument | description |
|---|---|
| `width_m`, `length_m`, `height_m` | room size in metres, 0.5 to 40 |
| `absorption` | surface reflectivity, 0.02 to 0.95. Bare tile or concrete around 0.05, plaster 0.15, carpeted 0.3, heavily treated 0.5 |
| `mic_position`, `source_position` | `center`, `corner` or `near wall` |
| `output_path` | a folder, or a full path ending in `.wav` |

Output is a stereo 48 kHz 24-bit WAV, peak-normalised, capped at 20 seconds.
Out-of-range values are clamped rather than rejected, and the reply says so.

Ranges, defaults and the parameters that shape the sound are in
[`src/mcp_rir/config.py`](src/mcp_rir/config.py).

## Roadmap

- [x] **Stereo output**, 48 kHz 24-bit, peak-normalised.
- [x] **Per-request output path**, so files land where you ask.
- [ ] **Microphone directivity.** The pair is currently two omnidirectional
      capsules, the weakest option for stereo image. Cardioid, hypercardioid
      and figure-of-eight patterns would allow real techniques (XY, ORTF,
      Blumlein) and widen the image considerably.
- [ ] **Multichannel output.** Quad and octophonic. Adding microphones to the
      same simulation is inexpensive; the work is picking layouts that
      convolvers actually accept.
- [ ] **Ambisonic B-format** (first order, W/X/Y/Z). Higher priority than a
      fixed quad, since it decodes to any speaker arrangement afterwards.
- [ ] **Room rendering.** An image of the simulated geometry with mic and
      source positions, written next to the WAV, to see what was generated
      without loading the file.
- [ ] **Non-shoebox geometry.** Arbitrary polygonal footprints extruded to 3D:
      L-shaped rooms, narrow corridors, concave spaces that focus reflections.
      No new dependencies needed.
- [ ] **Post-processing tool.** Reshaping an existing impulse response:
      reversed decay, gated tails, extreme time stretch. Taking a file path
      means it would work on impulse responses not generated here.
- [ ] **Tuning.** The default ranges are informed guesses, not yet adjusted by
      ear.

Suggestions and contributions welcome.

## Development

```
git clone https://github.com/tbimbato/MCP_RiR
cd MCP_RiR
pip install -e .
```

Point the configuration at that checkout:

```json
{
  "mcpServers": {
    "rir": {
      "command": "/path/to/your/python",
      "args": ["-m", "mcp_rir.server"]
    }
  }
}
```

## License

MIT