Skip to main content
Glama
README.md
# 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

A3.5/5.0

Scored across 7 tools

Disambiguation4/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness5/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues