# AudioMade MCP

[AudioMade](https://audiomade.app) brings game-ready AI sound effects into
compatible coding assistants through the Model Context Protocol (MCP).

Describe the interaction you are building, generate four real sound candidates,
listen to each option, and choose one. AudioMade installs only the selected WAV
into your Unity, Godot, or generic game project.

## Why this MCP server exists

Sound generation should not silently make creative decisions or modify a game
project before the developer hears the result. AudioMade uses a controlled
human-in-the-loop workflow:

```text
Describe the sound
      |
Generate four candidates
      |
Listen and choose 1, 2, 3, or 4
      |
Install only the selected WAV
      |
Connect it to the project's existing audio system
```

Generation is asynchronous, so an agent can continue implementing the game
feature while the audio renders.

## Features

- Four playable candidates for every generation
- Explicit user selection before installation
- Unity, Godot, and generic project destinations
- Safe path validation
- No silent file overwrite
- UI, gameplay, impact, weapons, Foley, creature, sci-fi, cinematic, ambience,
  music, horror, retro, and cartoon sound families
- Local candidate preview support
- WAV installation into the project

## Requirements

- Node.js 20 or newer
- An AudioMade account
- An `AUDIOMADE_API_KEY` created from the AudioMade MCP setup screen
- A compatible MCP client

Create an account at [audiomade.app](https://audiomade.app). Keep the API key
private. It can use generation credits associated with your account.

## Install from source

```bash
git clone https://github.com/yasib48/audiomade-mcp.git
cd audiomade-mcp
corepack enable
pnpm install --frozen-lockfile
pnpm build
```

Set the key in the environment used by your MCP client:

```text
AUDIOMADE_API_KEY=your_private_key
```

Run the server with:

```bash
node server/index.js
```

## MCP client configuration

Use an absolute path to `server/index.js` in your client configuration:

```json
{
  "mcpServers": {
    "audiomade": {
      "command": "node",
      "args": ["/absolute/path/to/audiomade-mcp/server/index.js"],
      "env": {
        "AUDIOMADE_API_KEY": "your_private_key"
      }
    }
  }
}
```

Do not commit a configuration file containing a real key. The exact config file
location depends on the MCP client.

## Tools

| Tool | Purpose |
| --- | --- |
| `get_audio_capabilities` | Read supported sound families and workflow requirements |
| `get_candidate_audio` | Load existing candidate previews for a compatible picker UI |
| `generate_sound_candidates` | Start a four-candidate generation job |
| `get_sound_candidates` | Check the job and return real playable candidates |
| `select_sound_candidate` | Record the user's explicit 1 to 4 choice |
| `install_sound_candidate` | Copy only the selected WAV into the game project |

## Example request

```text
Create a short stone landing sound for this player controller. Make four
options, let me listen to them, and do not add anything until I choose one.
```

## Development

```bash
pnpm install
pnpm build
pnpm test
```

The tests use mocked API responses and temporary directories. They do not spend
generation credits or modify a real game project.

## Privacy and security

- The API key is read from the local process environment.
- Generated candidates are stored temporarily on the local machine.
- Installation is restricted to a validated path inside the supplied project.
- Existing files are not overwritten unless the user explicitly allows it.
- Never include a real API key, generated user audio, or private project data in
  an issue or pull request.

See the [AudioMade privacy policy](https://audiomade.app/privacy) and
[terms](https://audiomade.app/terms) for the hosted service.

## License

The MCP client code in this repository is available under the [MIT License](LICENSE).
Use of the hosted AudioMade service is governed separately by the AudioMade
terms of service.

AudioMade is not affiliated with Unity Technologies or the Godot Engine project.