# Your AI assistant

> Let Claude, Cursor or another assistant search your Library, with recipes.

Ask the assistant you already use for **"three dusty snares, not claps"**, and it searches *your* Library in Mixel, then hands you a crate to audition. It can't move, tag, rename, copy or delete anything. You decide what to keep.

## Turn it on

In Mixel, open **Settings › Your assistant** and turn on **Let an assistant search your Library**. To get crates as well as answers, turn on **It can propose crates** too. Both are off until you turn them on, and with the first off, no assistant can reach your Library.

## Connect your assistant

Your assistant starts Mixel itself, as a small helper with no window, so there's nothing else to install. Mixel must be open for a search to work.

**Claude Desktop**
In **Settings › Your assistant**, choose **Connect** beside Claude Desktop, then quit and reopen Claude Desktop. The row says **Connected** after its first search.

**Claude Code**
Run this once in Terminal. `--scope user` makes it work in every project:

```sh
claude mcp add --scope user mixel -e MIXEL_ASSISTANT=claude-code -- /Applications/Mixel.app/Contents/MacOS/Mixel --mcp
```

**Copy the command** beside Claude Code in Mixel copies it for you.

**Cursor**
Choose **Connect** beside Cursor in **Settings › Your assistant**, then restart Cursor. Or add this to `~/.cursor/mcp.json`:

```json
{ "mcpServers": { "mixel": { "command": "/Applications/Mixel.app/Contents/MacOS/Mixel", "args": ["--mcp"], "env": { "MIXEL_ASSISTANT": "cursor" } } } }
```

**Other assistants**
Any assistant that runs local MCP servers works: the command `/Applications/Mixel.app/Contents/MacOS/Mixel` with the argument `--mcp`, over stdio. A settings file with `mcpServers` takes the same entry as Cursor's.

If you keep Mixel somewhere other than Applications, use that path.

## Recipes

Say these to your assistant. The calls it makes are underneath; `s1`, `sb`… are short ids Mixel gives it for sounds it was shown. Crates appear in the sidebar under **From your assistant**: audition with ↑ and ↓, press **Y** to keep a sound (it goes to Favorites) and **N** to take it out.

**Find a kick like this one.** "Find me kicks like Kick Punchy 03, but deeper. Put five in a crate." It finds the sound by name first, since it can only start from a sound it was shown:

```json
library_search {"want": "Kick Punchy 03"}
library_search {"like": "s1", "want": "deep kick"}
propose_crate  {"title": "Like Kick Punchy 03", "request": "kicks like it, deeper", "ids": ["sb", "sa", "sc"]}
```

**More like one you found.** Hand it a sound by name: "I found Rhodes Chords 91 Bbm. Find more loops like it in the same key."

```json
library_search {"want": "Rhodes Chords 91 Bbm"}
library_search {"like": "sg", "filters": {"type": "loop", "key": "Bb minor"}}
```

**Build a sample pack.** "Build me a lo-fi kit at 90 bpm in F minor: kicks, snares (no claps), hats, a drum loop and a keys loop." One search per part, then one crate of up to 50 sounds. `avoid` is a hard rule: not even a layered "clap snare" comes back.

```json
library_search {"want": "dusty snare", "avoid": ["clap"]}
library_search {"want": "lofi drum loop", "filters": {"bpm": [86, 94]}}
library_search {"want": "rhodes keys", "filters": {"key": "F minor"}}
```

**More than ten of one thing.** "Pick 30 kicks for a pack." A reply with more sounds has `next`; your assistant sends it back as `offset`:

```json
library_search {"want": "kick", "filters": {"type": "one-shot"}}
library_search {"want": "kick", "filters": {"type": "one-shot"}, "offset": 10}
```

**Sort a folder by instrument.** "Tag my Drum Kits by instrument." Your assistant can't tag, and can't search by folder: it makes a crate per instrument from your whole Library instead (`want: "kick"`, then snares, then hats). Keep or drop each sound, and add your own tags in the inspector. Mixel already reads instruments from file and folder names, so many sounds are found as "kick" without a tag.

## What your assistant sees

File names, a few facts (type, key, tempo, length) and, as a word, how sure Mixel is: `yours` (you tagged it), `named` (its name says so) and `detected` (Mixel heard it) are said as "these are"; `sounds_like` is a guess by ear, said as "these might fit".

It never receives audio, a file's path, a folder's name, your notes or a score, and each reply is small: ten sounds at most. **Settings › Your assistant** shows exactly what it receives for one sound, and **What your assistant did** lists its calls from the last 30 days, kept on this Mac. The assistant's provider sees what the assistant reads.

| Tool | What it does |
| --- | --- |
| `library_overview` | How many sounds, and how many of each kind of thing. Counts only. |
| `library_search` | Up to 10 sounds for `want`, without `avoid`, or `like` a sound it was shown and `unlike` others, narrowed by `type`, `key`, `bpm` and `length`. `next` brings the next 10, up to the first 200. |
| `propose_crate` | A crate of up to 50 sounds it was shown, with a title and your request. |

Filters read the way you'd type them into Mixel: `"Fm"` and `"A# minor"` find F minor and B♭ minor, and `"bpm": 90` means 86 to 94. There's no filter for folders, collections or favorites.

## When something's off

| Code | What happened | What to do |
| --- | --- | --- |
| `library_search_off` | Mixel is closed, or the first switch is off. | Open Mixel and turn it on. |
| `crates_off` | **It can propose crates** is off. | Turn it on, or ask for a list. |
| `not_ready` | Sounds *like* one need the sound model, which isn't there or is still working. | Search with words. The model is in **Settings › Library**. |
| `unknown_id` | The id is from before Mixel restarted. | Ask again. |

Other codes (`bad_input`, `too_many`, `timeout`) come with a fix your assistant follows by itself. **Claude Desktop still says "Added"?** Restart it; the row turns to **Connected** at its first search.

Building an app? `mixel mcp`, the [server for coding agents](https://docs.0x1audio.com/mcp.md), has these three tools too, from `mixel` 0.3.5.