Skip to main content
Glama

ampache-mcp

MCP connector for a self-hosted 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

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.

{
  "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.

Related MCP server: immich-mcp

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:

{ "action": "songs", "offset": 0, "limit": 2 }

Search titles (API 8 search is an advanced-search alias; rule_1 is required):

{
  "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:

{ "action": "playlist_create", "name": "Road" }

Execute it only when AMPACHE_ALLOW_WRITES is true and confirm is boolean true:

{ "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 (AGPL-3.0, playback through mpv, Last.fm, lyrics, radio) and 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.

Available Tools

7 tools
ampache_catalogsB
Destructive

Catalogs, catalog tasks (add_to_catalog, clean_catalog, verify_catalog, update_catalog, gather_art), catalog file/folder, flag, rate, record_play, and song_delete. Writes run only when confirm is true and AMPACHE_ALLOW_WRITES=true. List actions default to offset 0 and limit 25 (max 500). Actions: catalog, catalog_action, catalog_add, catalog_create, catalog_delete, catalog_file, catalog_folder, catalogs, flag, rate, record_play, scrobble, song_delete, update_art, update_artist_info, update_from_tags.

Inputs: action (required), id, uri, date, +29 more.

ampache_libraryC
Read-only

Artists, albums, songs, genres, labels, licenses, search, advanced search, stats, folders, and song stream URLs. Media bytes are never downloaded. Writes run only when confirm is true and AMPACHE_ALLOW_WRITES=true. List actions default to offset 0 and limit 25 (max 500). Actions: advanced_search, album, album_disk, album_disk_songs, album_disks, album_songs, albums, artist, artist_albums, artist_songs, artists, folders, genre, genre_albums, genre_artists, genre_songs, genres, get_similar, label, label_artists, labels, license, license_songs, licenses, search, search_group, search_rules, song, song_tags, songs, stats, url_to_song.

Inputs: action (required), add, url, cond, +20 more.

ampache_playlistsB
Destructive

Playlists and smartlists: list, get, songs, create, edit, add, remove, generate, hash, and delete. Writes run only when confirm is true and AMPACHE_ALLOW_WRITES=true. List actions default to offset 0 and limit 25 (max 500). Actions: playlist, playlist_add, playlist_create, playlist_delete, playlist_edit, playlist_generate, playlist_hash, playlist_remove, playlist_remove_song, playlist_songs, playlists, smartlist, smartlist_delete, smartlist_songs, smartlists, user_playlists, user_smartlists.

Inputs: action (required), id, add, cond, +24 more.

ampache_podcastsB
Destructive

Podcasts and episodes: list, get, create, edit, delete, and feed update. Writes run only when confirm is true and AMPACHE_ALLOW_WRITES=true. List actions default to offset 0 and limit 25 (max 500). Actions: podcast, podcast_create, podcast_delete, podcast_edit, podcast_episode, podcast_episode_delete, podcast_episodes, podcast_update, podcasts, update_podcast.

Inputs: action (required), add, url, cond, +16 more.

ampache_sharesB
Destructive

Shares: list, get, create, edit, and delete. Share tokens are redacted. Writes run only when confirm is true and AMPACHE_ALLOW_WRITES=true. List actions default to offset 0 and limit 25 (max 500). Actions: share, share_create, share_delete, share_edit, shares.

Inputs: action (required), add, cond, sort, +12 more.

ampache_systemB
Destructive

Ampache ping, session goodbye, index, list, browse, and now_playing. Writes run only when confirm is true and AMPACHE_ALLOW_WRITES=true. List actions default to offset 0 and limit 25 (max 500). Actions: browse, goodbye, index, list, now_playing, ping.

Inputs: action (required), type, exact, limit, +6 more.

ampache_usersA
Destructive

Users and preferences (admin): list, get, create, edit, delete, and preference get/set. Passwords are never logged. Writes run only when confirm is true and AMPACHE_ALLOW_WRITES=true. List actions default to offset 0 and limit 25 (max 500). Actions: preference_create, preference_delete, preference_edit, system_preference, system_preferences, user, user_create, user_delete, user_edit, user_preference, user_preferences, users.

Inputs: action (required), city, type, email, +23 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables managing a self-hosted media library through its HTTP API, with scoped toolsets, confirm-gated writes, dry-run previews, and read caching. Supports libraries, items, collections, playlists, podcasts, sessions, stats, tags, genres, and administrative operations.
      13
      131 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Connects MCP clients to a self-hosted photo library through its REST API, exposing assets, albums, people, search, and optional administrative toolsets with read-only defaults and confirm-gated writes. It supports stdio and localhost Streamable HTTP transports.
      5
      87 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects MCP clients to a self-hosted Seafile server through the seahub HTTP API, exposing libraries, files, search, sharing, and optional admin operations over stdio or Streamable HTTP. It defaults to read-focused tools and gates writes behind confirmation, with token redaction and dry-run previews.
      9 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP clients to interact with a self-hosted comic/library server through its HTTP API, exposing libraries, series, books, collections, readlists, metadata, and administrative operations with read/write safety controls over stdio or Streamable HTTP.
      7
      MIT