Content
# makid-mcp
An [MCP](https://modelcontextprotocol.io) server for querying and safely editing the
[MAKID](https://www.makidapp.com) music-catalog database — so an AI assistant (or you, through
one) can tag, genre, key, and triage your project library by voice instead of by hand-written SQL.
[MAKID](https://www.makidapp.com) (by Templar Labs LLC) helps Ableton Live producers organize
projects, bounces, and notes in one workspace. This is an independent, unofficial tool — not
affiliated with or endorsed by Templar Labs.
## What it does
MAKID stores your projects, tracks, genres, tags, and statuses in a local
[Prisma](https://www.prisma.io)-managed SQLite database. There's a lot you can do with that data
that the GUI makes slow: "show me every un-genred project under 100 BPM", "tag all of these
*Dark*", "set the key on these twelve sketches". Doing it by hand means writing raw SQL and
getting the details exactly right — Prisma's ISO-8601 timestamp format, lowercase genres,
Capitalized tags, valid key values, idempotent join rows. Get one wrong and the data drifts.
`makid-mcp` exposes those operations as a small set of MCP tools with the rules baked in. Reads
go through a read-only connection; every write takes an automatic backup first, runs in a single
transaction, and refuses to corrupt the schema.
## Features
- **Query** projects with combined filters (genre, tag, status, tier, progress, key, BPM range, name).
- **Inspect** a project's full detail — tracks, keys, tempos, Ableton Live version, associations.
- **Stats** for a labeling pass: counts of untagged / un-genred / keyless projects, plus
tier/progress/key distributions.
- **Edit** safely: assign/remove genres, tags (with `#RRGGBB` color), and statuses; set a track's
key; edit tier / progress / notes; manage the tag catalog.
- **Format-correct writes**: ISO-8601 timestamps, lowercase genres, Capitalized tags, validated
keys (MAKID's fixed 24-value set) — all enforced automatically.
- **Safety first**: automatic pre-write backups with retention, idempotent join inserts,
foreign-key enforcement, a SELECT-only raw-query escape hatch, and a warning (or hard block)
when MAKID is running.
## Requirements
- macOS with [MAKID](https://www.makidapp.com) installed (built against the 0.7.2 schema).
- Python 3.11+.
## Install
```bash
git clone https://github.com/ecarter/makid-mcp.git
cd makid-mcp
pip install -e .
```
### Register with an MCP client
Add to your client's MCP config (e.g. Claude Code's `~/.claude/settings.json`) — either via the
installed console script:
```json
{
"mcpServers": {
"makid": { "command": "makid-mcp" }
}
}
```
or by pointing at the module directly:
```json
{
"mcpServers": {
"makid": { "command": "python", "args": ["-m", "makid_mcp.server"] }
}
}
```
See [`examples/claude_mcp_config.json`](examples/claude_mcp_config.json).
## Configuration
All optional, via environment variables:
| Variable | Default | Purpose |
| --- | --- | --- |
| `MAKID_DB_PATH` | `~/Library/Application Support/makid/MAKID.db` | Path to the database. |
| `MAKID_BACKUP_DIR` | next to the database | Where pre-write backups are written. |
| `MAKID_BACKUP_KEEP` | `10` | How many backups to retain (older ones are pruned). |
| `MAKID_BLOCK_WHEN_RUNNING` | off | If set (`1`/`true`), refuse writes while MAKID is running. |
## Tools
| Tool | Kind | Description |
| --- | --- | --- |
| `list_projects` | read | Filter projects by genre/tag/status/tier/progress/key/BPM/name. |
| `get_project` | read | Full detail for one project (by id or name). |
| `list_genres` / `list_tags` / `list_statuses` | read | Catalog entries with usage counts. |
| `stats` | read | Totals, distributions, and untagged/un-genred/keyless counts. |
| `query_sql` | read | Run a single read-only `SELECT` (writes rejected). |
| `assign_genre` / `remove_genre` | write | Genre membership (creates the genre if new). |
| `rename_genre` / `delete_unused_genre` | write | Genre-catalog management (rename merges into an existing target). |
| `assign_tag` / `remove_tag` | write | Tag membership (creates the tag, optional color). |
| `assign_status` / `remove_status` | write | Status membership. |
| `set_key` | write | Set a track's key (one of MAKID's 24 values). |
| `set_project_field` | write | Edit `tier`, `progress`, or `editorNotes`. |
| `create_tag` / `recolor_tag` / `delete_unused_tag` | write | Tag-catalog management. |
| `list_backups` / `restore_backup` | read/write | List and roll back to pre-write snapshots. |
## Safety & backups
- Every write **backs up the database first** to `MAKID.db.bak-YYYYMMDD-HHMMSS` and prunes to the
newest `MAKID_BACKUP_KEEP`. `restore_backup` rolls back (and snapshots first, so it's reversible).
- MAKID writes the same database, so concurrent edits are **last-writer-wins**. The server warns on
every write while MAKID is running; set `MAKID_BLOCK_WHEN_RUNNING=1` to forbid them outright.
- **Tag changes** may not show until you right-click → Resync in MAKID or restart it (the app caches
the tag palette). Genre and key changes appear live. Each tag tool returns this reminder.
## How it works
```
MCP client
│ tool call
▼
server.py ──► safety guard ──► backup ──► single write transaction ──► repository (SQL)
│ │
└────────────── read-only connection ───────────────────────────────────┘
```
- `validators.py` keeps every written value in MAKID's format.
- `db.py` separates read-only from transactional write connections and guards the raw-SQL tool.
- `backup.py` / `safety.py` handle snapshots and running-app detection.
- `repository.py` is the SQL layer; `server.py` is the thin MCP tool surface.
## Development
```bash
pip install -e ".[dev]"
pytest # tests run against a synthetic fixture — no real database needed
ruff check .
```
## Status
v0.1.0. Read and write tools are implemented and covered by tests against a synthetic
MAKID-shaped fixture.
## Limitations
- Built against the **MAKID 0.7.2** schema; a future MAKID release could change tables/columns.
- Single local database only (no MAKID Cloud sync awareness).
- `editorNotes` is written as plain text; MAKID also keeps a rich-text `editorNotesState`, so
notes set here may render plainly in the app.
- Tag visibility requires a MAKID resync/restart (see above).
## License
MIT © E. T. Carter. Not affiliated with MAKID or Templar Labs LLC.
