ampache-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PORT | No | HTTP listen port. Default 3000. | |
| AMPACHE_URL | Yes | Required. Ampache origin only, using http or https, with no userinfo, query, hash, or path. Example: http://127.0.0.1:18680. | |
| MCP_TRANSPORT | No | Transport mode: stdio (default) or http. | |
| AMPACHE_API_KEY | No | Ampache API key. Omit when using a username and password instead. Minimum 8 characters. | |
| AMPACHE_CONTACT | No | Contact string included in the User-Agent. Must not be a secret. | |
| AMPACHE_PASSWORD | No | Password for the configured user. | |
| AMPACHE_USERNAME | No | Username for the password handshake. | |
| AMPACHE_PER_MINUTE | No | Local sliding-window rate limit. Default 30. | |
| AMPACHE_TIMEOUT_MS | No | Upstream timeout in milliseconds. Default 20000. | |
| AMPACHE_ALLOW_WRITES | No | The literal value true is required before a confirmed write is sent. TRUE, 1, and empty do not enable writes. | |
| AMPACHE_API_KEY_FILE | No | Path to a chmod 600 file containing the API key, used when AMPACHE_API_KEY is omitted. | |
| AMPACHE_CACHE_TTL_SEC | No | Cache TTL for reads, in seconds. Default 0 (off). | |
| AMPACHE_PASSWORD_FILE | No | Path to a chmod 600 file containing the password, used when AMPACHE_PASSWORD is omitted. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| ampache_systemB | 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. |
| ampache_libraryC | 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. |
| ampache_playlistsB | 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. |
| ampache_catalogsB | 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. |
| ampache_sharesB | 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. |
| ampache_podcastsB | 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. |
| ampache_usersA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.