ampache-mcp
# ampache-mcp
MCP connector for a self-hosted [Ampache](https://github.com/ampache/ampache) 8.4.0 JSON API (`/server/json.server.php`, API 8). It speaks stdio and stateless Streamable HTTP on localhost.
Ampache is AGPL-3.0. This connector is MIT. It does not vendor Ampache source, schema, samples, or docs. It is not affiliated with Ampache.
`spec/api-inventory.json` is a hand-written list of JSON API method names, parameter names and types, and write flags. `scripts/gen-operations.mjs` maps each method to a tool action or an exclusion and writes `src/operations.ts` and `ampache.routes.json`. A method that is neither mapped nor excluded fails generation. Do not edit `src/operations.ts` by hand.
## Setup
```bash
npm install
npm run ci
npm start
npm run start:http
```
`npm start` speaks stdio. `npm run start:http` serves Streamable HTTP at `http://127.0.0.1:3000/mcp` and `GET /health`. HTTP mode has no authentication of its own. Keep it on localhost.
```json
{
"mcpServers": {
"ampache": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"AMPACHE_URL": "http://127.0.0.1:18680",
"AMPACHE_USERNAME": "admin",
"AMPACHE_PASSWORD": "...",
"AMPACHE_ALLOW_WRITES": "false"
}
}
}
}
```
Use an API key or a username and password, not both. The connector never prints the key, the password, the handshake passphrase, or the session token.
Isolated loopback scripts live under `/workspace/tools/ampache` (`start.sh`, `stop.sh`). They keep MariaDB data, secrets, and generated audio under `/tmp/ampache-mcp-runtime`. The connector does not start Ampache.
## Config
| Variable | Meaning |
| --- | --- |
| `AMPACHE_URL` | Required. Origin only, `http` or `https`, no userinfo, query, hash, or path. Example `http://127.0.0.1:18680`. |
| `AMPACHE_API_KEY` | API key. Omit when using username and password. Minimum 8 characters. |
| `AMPACHE_API_KEY_FILE` | chmod 600 file used when `AMPACHE_API_KEY` is omitted. |
| `AMPACHE_USERNAME` | Username for password handshake. |
| `AMPACHE_PASSWORD` | Password for that user. |
| `AMPACHE_PASSWORD_FILE` | chmod 600 file used when `AMPACHE_PASSWORD` is omitted. |
| `AMPACHE_ALLOW_WRITES` | Literal `true` is required before a confirmed write is sent. `TRUE`, `1`, and empty do not enable writes. |
| `AMPACHE_CONTACT` | Contact string in the User-Agent. Must not be a secret. |
| `AMPACHE_PER_MINUTE` | Local sliding window. Default 30. |
| `AMPACHE_CACHE_TTL_SEC` | Cache TTL for reads. Default 0 (off). |
| `AMPACHE_TIMEOUT_MS` | Upstream timeout. Default 20000. |
| `MCP_TRANSPORT` | `stdio` (default) or `http`. |
| `PORT` | HTTP listen port. Default 3000. |
Handshake sends credentials in the JSON body, not the URL. Later calls send `Authorization: Bearer` with the session token. One re-handshake runs when Ampache reports error `4701` with a session-expired message. Redirects are refused. Other requests are not retried.
List actions default to `offset` 0 and `limit` 25. `limit` cannot exceed 500.
## Tools
Seven tools. Every call takes `action`. Writes also take boolean `confirm`.
| Tool | Role |
| --- | --- |
| `ampache_system` | `ping`, `goodbye`, `index`, `list`, `browse`, `now_playing`. |
| `ampache_library` | Artists, albums, songs, genres, labels, licenses, folders, search, advanced search, stats. Song JSON includes a stream URL. Media bytes are not downloaded. |
| `ampache_playlists` | Playlists and smartlists: list, get, songs, create, edit, add, remove, generate, delete. |
| `ampache_catalogs` | Catalogs, catalog tasks, catalog file and folder, flag, rate, record play, scrobble, tag and art refresh, song delete. |
| `ampache_shares` | List, get, create, edit, delete. Share secrets are redacted. |
| `ampache_podcasts` | Podcasts and episodes: list, get, create, edit, delete, feed update. |
| `ampache_users` | Users and preferences (admin). Passwords are redacted. |
98 of 155 inventoried methods are mapped. 38 of those are writes. The other 57 are excluded. Counts and reasons are in `ampache.routes.json`.
Excluded groups: handshake and device pairing (the client performs handshake), password-reset mail and public registration, in-place server upgrades, binary stream/download/art/upload, localplay and democratic playback, social timelines, video and deleted-object archives, bookmarks, live radio, playlist folders, collections, external metadata, and Sonic fingerprint match.
## Examples
Read two songs:
```json
{ "action": "songs", "offset": 0, "limit": 2 }
```
Search titles (API 8 `search` is an advanced-search alias; `rule_1` is required):
```json
{
"action": "advanced_search",
"operator": "and",
"type": "song",
"rule_1": "title",
"rule_1_operator": "0",
"rule_1_input": "Tone"
}
```
Dry-run a playlist create. Nothing is sent:
```json
{ "action": "playlist_create", "name": "Road" }
```
Execute it only when `AMPACHE_ALLOW_WRITES` is `true` and `confirm` is boolean true:
```json
{ "action": "playlist_create", "name": "Road", "confirm": true }
```
Catalog tasks on API 8 are `add_to_catalog`, `clean_catalog`, `verify_catalog`, `update_catalog`, `gather_art`, `garbage_collect`, and `scan_catalog_folders`.
## Safety
A write is sent only when `confirm` is boolean `true` and `AMPACHE_ALLOW_WRITES` is the literal `true`. Any other combination returns a dry-run preview and performs no write HTTP. The string `"true"` is rejected. GET-shaped Ampache mutations are still marked writes and use POST.
Redaction is request-scoped. It covers the API key, password, derived passphrase, session token, user passwords, share secrets, URL userinfo, and sensitive keys at any depth, including percent-encoded and JSON-escaped forms. Secrets shorter than 8 characters are not substring-masked; if an upstream message contains one, the detail is replaced with a generic sentence. Nothing is accumulated across requests.
Unknown fields and the wrong action are rejected before HTTP.
## Provenance and rivals
Route facts in `spec/api-inventory.json` were written by hand for Ampache 8.4.0 (6 Nov 2026). They are not a copy of upstream files. The generator checks `sourceSha256` and `routeTreeSha256`.
No dedicated Ampache MCP turned up in a GitHub repository search for `ampache mcp` (0 hits on 17 Nov 2026) or in npm search. Adjacent Subsonic clients are different products: [Blakeem/Navidrome-MCP](https://github.com/Blakeem/Navidrome-MCP) (AGPL-3.0, playback through mpv, Last.fm, lyrics, radio) and [anatoliv/baton](https://github.com/anatoliv/baton) (MIT, macOS player). This connector is a native Ampache JSON API client with catalogs, shares, podcasts, user admin, a two-key write gate, and redaction. It does not play audio and it does not speak Subsonic. Navidrome-MCP source was not read.
## Live check
`scripts/live-check.mjs` talks to a real server over stdio. It unsets `DATABASE_URL`. Set `AMPACHE_URL`, `AMPACHE_USERNAME`, and `AMPACHE_PASSWORD` or `AMPACHE_PASSWORD_FILE`. It prints pass or fail lines only. See `LIVE-CHECK.md` for the isolated run. The script does not run inside `npm run ci`.
## License
MIT. See `LICENSE`. Ampache itself remains AGPL-3.0.
TDQS
Scored across 7 tools
The tools are grouped into clear domains (system, library, playlists, catalogs, shares, podcasts, users), so most selections are straightforward. However, ampache_catalogs bundles catalog management with song-level actions like flag, rate, scrobble, song_delete, and update_art that conceptually overlap with ampache_library, and ampache_system's generic browse/list actions can be confused with library browsing.
All seven tools follow a consistent ampache_<domain> lowercase snake_case pattern. Minor singular/plural variation (ampache_library vs. ampache_playlists) is natural for uncountable domains and does not create confusion.
Seven tools is well within the ideal range, and each domain category earns its place. The action-dispatch design keeps the exposed tool count manageable while covering a broad API.
Coverage spans system/session operations, library browsing and search, playlists and smartlists, catalogs, shares, podcasts, users, and preferences, including admin preference operations. No obvious lifecycle gaps exist for an Ampache API client.