Skip to main content
Glama
audiobookshelf-mcp

audiobookshelf-mcp

by ni-c

audiobookshelf-mcp

CI OpenSSF Scorecard Socket Badge Glama score npm version container image HTTP via mcp-hub docs sponsor

A Model Context Protocol (MCP) server for Audiobookshelf, the self-hosted audiobook and podcast server.

Lets MCP clients like Claude Code, Claude Desktop or Codex browse your libraries, answer questions about what you own and what you have listened to, and — unless you switch it off — keep your listening progress, bookmarks, collections and playlists up to date: 44 tools, 29 read and 15 write.

Forty-four tools is the ceiling, not the floor: AUDIOBOOKSHELF_ALLOW_TOOLS=essential registers a curated eight instead, and a model picks the right tool far more reliably from eight than from forty-four — see choosing which tools load.

What makes it different

Every response is a projection, not the raw object. An expanded library item carries every audio file, track and chapter with full ffprobe metadata. The media tools answer with a compact shape instead, and detail="full" is there for when the raw object really is what you want.

Twenty-nine of the forty-four tools only read. AUDIOBOOKSHELF_READ_ONLY=true registers those and nothing else, so a write tool is absent from tools/list rather than refused when it is called.

The six tools that take something out ask a person first, through MCP elicitation — a dialog the model cannot answer on its behalf, falling back to a single-use token bound to the exact targets where the client cannot show one.

Related MCP server: calibre-manager

Requirements

  • Node.js 24 or newer

  • Audiobookshelf 2.26.0 or newer — earlier versions have no API keys

  • An Audiobookshelf API key

Getting an API key

API keys are managed by an admin under Settings → Users → API Keys. A key acts on behalf of exactly one Audiobookshelf user and inherits that user's permissions, so a key issued for a normal account cannot see libraries that account cannot see, and cannot delete anything unless that account may delete. The key is shown only once, at creation.

Configuration

Variable

Required

Description

AUDIOBOOKSHELF_URL

yes

Base URL of the instance, e.g. https://abs.example.com. Must not contain credentials.

AUDIOBOOKSHELF_API_KEY

yes

API key, sent as Authorization: Bearer …

AUDIOBOOKSHELF_READ_ONLY

no

true registers only the 29 read tools

AUDIOBOOKSHELF_INSECURE_TLS

no

true accepts self-signed certificates — scoped to this connection, not process-wide

AUDIOBOOKSHELF_ALLOW_TOOLS

no

Comma-separated tool names, list_* prefixes, or essential for a curated preset

AUDIOBOOKSHELF_DENY_TOOLS

no

Same syntax; removed from whatever AUDIOBOOKSHELF_ALLOW_TOOLS left

ELICITATION

no

false replaces the approval dialog with the two-call token. Not prefixed

The server starts without configuration: it completes the MCP handshake and lists its tools, and every call then fails with the setup instructions. That is deliberate, so registries and sandbox inspectors can introspect it.

Choosing which tools load

AUDIOBOOKSHELF_ALLOW_TOOLS and AUDIOBOOKSHELF_DENY_TOOLS take comma-separated tool names; a trailing * matches a whole family. essential is a curated preset of eight: list_libraries, search_library, list_library_items, get_library_item, get_item_chapters, list_items_in_progress, get_media_progress, set_media_progress.

AUDIOBOOKSHELF_ALLOW_TOOLS=essential
AUDIOBOOKSHELF_ALLOW_TOOLS=search_library,get_library_item,set_media_progress
AUDIOBOOKSHELF_DENY_TOOLS=delete_*

An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a tool — an absent tool is not something anyone traces back to an environment variable. A filtered tool is never registered, so it is absent from tools/list and unknown to tools/call alike, exactly like a write tool under AUDIOBOOKSHELF_READ_ONLY.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools.

Installation

Claude Code

claude mcp add audiobookshelf \
  -e AUDIOBOOKSHELF_URL=https://abs.example.com \
  -e AUDIOBOOKSHELF_API_KEY=… \
  -- npx -y audiobookshelf-mcp

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "audiobookshelf": {
      "command": "npx",
      "args": ["-y", "audiobookshelf-mcp"],
      "env": {
        "AUDIOBOOKSHELF_URL": "https://abs.example.com",
        "AUDIOBOOKSHELF_API_KEY": "…"
      }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.audiobookshelf]
command = "npx"
args = ["-y", "audiobookshelf-mcp"]
env = { AUDIOBOOKSHELF_URL = "https://abs.example.com", AUDIOBOOKSHELF_API_KEY = "…" }

Docker

Multi-arch, with SBOM and build provenance:

docker run -i --rm \
  -e AUDIOBOOKSHELF_URL=https://abs.example.com \
  -e AUDIOBOOKSHELF_API_KEY=… \
  ghcr.io/ni-c/audiobookshelf-mcp

-i is required — the protocol runs over stdin and stdout. There is no port to publish. More client recipes, including how to keep the key off the docker run command line, are in the client guide.

Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — reaches audiobookshelf-mcp through mcp-hub: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end.

Its /config/mcp.json uses Claude Code's format, so the entry is the one you already have:

{
  "mcpServers": {
    "audiobookshelf": {
      "command": "npx",
      "args": ["-y", "audiobookshelf-mcp"],
      "env": { "AUDIOBOOKSHELF_ALLOW_TOOLS": "essential" },
      "denyTools": ["delete_*"]
    }
  }
}

allowTools and denyTools there are the hub's own per-server filter, which is not the same thing as *_ALLOW_TOOLS in env — the difference, and the mistake it invites, are in the client guide.

Tools

Every tool declares an outputSchema and answers with structuredContent alongside the text block, so a client can use the result without parsing prose. Seven tools that answered with a sentence — "Collection col_1 deleted." — now answer with the fields as well.

The tools that report library metadata carry untrusted: true and source: "audiobookshelf" as fields: book descriptions pulled from metadata providers, podcast feed summaries and episode titles are all written by someone else, and so are the bookmark titles and selected tags of an account and the titles of a library's longest and largest items. The rest are without it — an id this server was given, a position it was asked to store, the version string of the instance, and the library names and folder paths the operator typed.

The documents are described as open objects with the top-level keys this server builds. detail: "full" hands the API record back whole, so the same tool answers with far more keys than it names — and the SDK validates each result against its schema before it goes out, which is exactly why a strict shape would be wrong here.

get_personalized_shelves answers {items: [...]} rather than the bare array the API sends: a schema whose root is an array is served to a 2025-era client rewritten as {result: …}, so it would otherwise answer in two shapes.

Reading

Tool

What it does

list_libraries

The accessible libraries with id, name and media type — the entry point

get_library

One library with its folders and settings

get_library_stats

Item, author and genre counts, total duration and size

get_library_filter_data

The filterable values of a library: authors, genres, tags, series, narrators, languages, publishers

list_library_items

Items of a library, paginated, sortable, filterable

search_library

Full-text search across books, podcasts, series, authors, narrators and tags

get_personalized_shelves

The home screen shelves: Continue Listening, Recently Added, …

list_series / get_series

Series with book count and total duration

list_authors / get_author

Authors, optionally with their items

list_tags / list_genres

All tags / genres used on the server

get_library_item

One book or podcast with metadata, tags and your progress

get_item_chapters

The chapter list of a book, separate because it can be long

get_podcast_episode

One episode with publication date, duration and description

list_recent_episodes

Newest episodes of a podcast library

get_me

The user the API key acts for, with permissions and libraries

list_items_in_progress

Started but unfinished items across all libraries

get_media_progress

Position, percentage and finished state for one item

get_listening_stats

Total time, time per day and per weekday, most listened items

get_year_stats

The "year in review" figures for one calendar year

list_listening_sessions

Playback sessions with device, position and time listened

list_bookmarks

Bookmarks, all of them or those of one item

list_collections / get_collection

Collections — shared, ordered groups of books

list_playlists / get_playlist

Playlists — private per user, books or episodes

get_server_status

Version and initialization state of the server

Writing

Tool

What it does

set_media_progress

Set position, mark finished or unfinished, hide from Continue Listening

delete_media_progress 👤

Delete a progress record — the listening history of that item

create_bookmark / update_bookmark / delete_bookmark 👤

Named positions in a book

create_collection / update_collection / delete_collection 👤

Collections

add_books_to_collection / remove_books_from_collection 👤

Collection membership

create_playlist / update_playlist / delete_playlist 👤

Playlists

add_items_to_playlist / remove_items_from_playlist 👤

Playlist membership

👤 asks a person through MCP elicitation · falls back to a two-call confirm_token where the client cannot show a dialog.

Response size

Audiobookshelf returns very large objects — an expanded library item carries every audio file, track and chapter with full ffprobe metadata. Every tool that returns media therefore answers with a compact projection by default and accepts detail: "full" for the raw object.

Three bounds, because one is not enough:

  • A response ceiling of 5 MB. content-length is checked before a byte is read and a chunked body is counted while reading, so an oversized answer is refused rather than parsed.

  • A result ceiling of 100 000 bytes, applied in jsonResult — so it covers detail: "full" too. Whole entries are dropped, never characters: a truncated document is not a smaller answer, it is an unparseable one. The result then carries a truncated block naming what to call instead.

  • A cap on embedded members. A compact collection or playlist embeds the first 25 of its books or entries and reports the real count; get_collection and get_playlist return the whole membership for one of them.

list_library_items pages properly, with limit and page. Seven listing tools have neither — list_libraries, list_authors, list_tags, list_genres, list_collections, list_playlists and list_bookmarks — because the Audiobookshelf routes behind them return everything in one answer and take no paging parameters. library_id narrows the two collection routes; the rest are bounded by the ceilings above.

Filtering

list_library_items takes filter_group plus filter_value and builds the base64-encoded filter parameter the API expects. The valid values come from get_library_filter_data. A valued group without a value is rejected, because Audiobookshelf would silently answer with the unfiltered library instead.

filter_group="authors",  filter_value="<author id>"
filter_group="progress", filter_value="finished" | "in-progress" | "not-started" | "not-finished"
filter_group="issues"    (standalone, no value)

Not exposed, on purpose

No playback. Pausing, seeking and playing are a session state machine that belongs in a real client. set_media_progress covers "mark this finished" and "jump me to chapter 12"; your phone does the playing.

No administration, even with an admin key. There is no tool for user management, server settings, backups, cache purging, filesystem browsing, library or item deletion, metadata rewriting or file uploads. Those endpoints exist in Audiobookshelf; they are simply not wired up here, because the blast radius of a confused or manipulated model is bounded by the tool list.

Safety

  • Read-only mode. AUDIOBOOKSHELF_READ_ONLY=true does not register the write tools at all, rather than refusing them at call time.

  • A person is asked, not just told. The eight tools that can take something out — the three deletes, delete_bookmark, remove_books_from_collection, remove_items_from_playlist, and update_collection / update_playlist when they are asked to reorder, which replaces an order nobody can reconstruct — raise a real dialog through MCP elicitation, which the model cannot answer on its behalf. A plain confirm: true flag could be set by the model on the first try, or be talked into it by text coming out of the library.

    Where the client cannot show a dialog they fall back to a single-use token bound to the exact targets and expiring after five minutes. That fallback proves the call was made twice with the same arguments and nothing more, and the text says so rather than implying somebody approved. ELICITATION=false takes it deliberately; it never removes the guard. See Asking a person.

  • Confirmation prompts never quote API content. Collection and playlist names are user-supplied text and are read by a model, so the prompts name ids and counts only.

  • A 200 that is not JSON is an error. Returning the body as a string made an SSO portal or a captive proxy in front of the instance look like an empty library rather than like a failure.

  • Untrusted content is marked. Book descriptions come from metadata providers and podcast summaries come from RSS feeds — third parties write them. Every result carrying such content is labelled as data, not instructions.

  • The API key is deleted from the environment once the configuration has been read, so it is not visible to child processes or in /proc/<pid>/environ.

  • No redirects are followed (redirect: 'error'), so the Authorization header cannot be replayed against another host, and every request has a 15 second timeout.

  • Ids are validated before they enter a URL path.

  • Upstream error bodies are sanitized: HTML error pages are dropped, anything else is truncated to 2000 characters.

  • Progress updates send whitelisted fields only. The Audiobookshelf endpoint applies its payload to the progress record wholesale.

  • What this server cannot do, by design: no user management, no server settings, no backups, no cache purging, no filesystem browsing, no library or item deletion, no metadata rewriting, no file uploads.

One caveat that comes from Audiobookshelf itself: removing the last entry from a playlist deletes the playlist. remove_items_from_playlist says so in its result when it happens.

Documentation

The full guide, tool reference and security notes live at audiobookshelf-mcp.ni-c.de (source in docs/).

Development

npm install
npm run lint          # oxlint + prettier --check
npm run build         # tsc
npm test              # vitest
npm run test:coverage # with thresholds
npm run docs:tools    # regenerate docs/reference/tools.md from the registered tools

The table above is hand-curated; the complete tool reference with every parameter is generated from the code, and CI fails if the committed copy is stale. See CONTRIBUTING.md for a throwaway Audiobookshelf you can safely write to — the write tools change progress and bookmarks on the API key's own user, so don't develop against a library you care about.

The tool definitions were derived from the Audiobookshelf server source (server/routers/ApiRouter.js and the controllers) rather than from api.audiobookshelf.org, which is out of date in several places — the filter data endpoint is /filterdata not /filter, progress updates are PATCH /api/me/progress/:id not POST /api/me/progress, and bookmarks live under /api/me/item/:id/bookmark.

Releasing

Tag-driven, no manual publish step:

  1. Move the [Unreleased] entries into a new ## [x.y.z] - YYYY-MM-DD section in CHANGELOG.md and bump package.json.

  2. npm run lint && npm run build && npm run test:coverage.

  3. Commit, then a signed annotated tag: git tag -s vx.y.z -m "vx.y.z".

  4. git push origin main vx.y.z.

release.yml then runs the tests, publishes to npm with provenance via Trusted Publishing (no token secret involved), creates the GitHub release from the CHANGELOG section, and publishes to the MCP registry as io.github.ni-c/audiobookshelf-mcp. ci.yml pushes the multi-arch image to GHCR on the same tag.

If the registry step fails, fix it on main and dispatch the Publish to MCP Registry workflow — do not re-run the tag job, which would check out the old tree.

Contributing

Issues, discussions and pull requests are welcome — see CONTRIBUTING.md. For vulnerabilities please use private reporting rather than a public issue; the policy is in SECURITY.md.

License

MIT © Willi Thiel

Available Tools

44 tools
add_books_to_collectionAdd books to collectionA
Idempotent

Adds one or more books to an existing collection. Books already in the collection are ignored; books from a different library are rejected.

Inputs: collection_id (required), library_item_ids (required). Returns: source, truncated, untrusted

add_items_to_playlistAdd items to playlistA

Appends books or podcast episodes to a playlist. All entries must come from the playlist’s library and match its kind — a podcast playlist needs an episode_id on every entry, a book playlist on none.

Inputs: items (required), playlist_id (required). Returns: source, truncated, untrusted

create_bookmarkCreate bookmarkA

Creates a bookmark at a position of a book for the API key’s user. The position in seconds is the bookmark’s identity — a second bookmark at the same second is rejected.

Inputs: time (required), title (required), library_item_id (required). Returns: source, created, bookmark, truncated, +1 more

create_collectionCreate collectionA

Creates a collection of books. Audiobookshelf rejects empty collections, so at least one library item id is required, and every item must be a book from the given library.

Inputs: name (required), library_id (required), library_item_ids (required), description. Returns: source, truncated, untrusted

create_playlistCreate playlistA

Creates a playlist for the API key’s user. Unlike a collection it may start out empty and it may hold podcast episodes.

Inputs: name (required), library_id (required), items, description. Returns: source, truncated, untrusted

delete_bookmarkDelete bookmarkA
DestructiveIdempotent

Deletes the bookmark at a given position. Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it.

Inputs: time (required), library_item_id (required), confirm_token. Returns: truncated, deleted_bookmark

delete_collectionDelete collectionA
DestructiveIdempotent

Deletes a collection. The books stay in the library, but the curated list and its order are gone. Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it. Requires an Audiobookshelf account with delete permission.

Inputs: collection_id (required), confirm_token. Returns: truncated, deleted_collection_id

delete_media_progressDelete media progressA
DestructiveIdempotent

Deletes a progress record of the API key’s user, which removes the listening history for that item — position, finished state and dates. Takes the media progress id (field "id" of get_media_progress), not the library item id. Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it.

Inputs: media_progress_id (required), confirm_token. Returns: truncated, deleted_progress_id

delete_playlistDelete playlistA
DestructiveIdempotent

Deletes a playlist. The media stays in the library. Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it.

Inputs: playlist_id (required), confirm_token. Returns: truncated, deleted_playlist_id

get_authorGet authorA
Read-onlyIdempotent

Fetches a single author, optionally with the library items attributed to them.

Inputs: author_id (required), detail, library_id, include_items. Returns: source, truncated, untrusted

get_collectionGet collectionA
Read-onlyIdempotent

Fetches one collection with the books it contains, in order.

Inputs: collection_id (required), detail. Returns: source, truncated, untrusted

get_item_chaptersGet item chaptersA
Read-onlyIdempotent

Returns the chapter list of a book with start and end times in seconds. Separate from get_library_item because long audiobooks can have hundreds of chapters.

Inputs: library_item_id (required). Returns: source, chapters, truncated, untrusted

get_libraryGet libraryA
Read-onlyIdempotent

Fetches a single library including its folders and scanner settings.

Inputs: library_id (required), detail. Returns: truncated

get_library_filter_dataGet library filter dataA
Read-onlyIdempotent

Returns the values that can be filtered on in this library: authors, genres, tags, series, narrators, languages and publishers, each with the id or name to pass to list_library_items as filter_value.

Inputs: library_id (required). Returns: source, truncated, untrusted

get_library_itemGet library itemA
Read-onlyIdempotent

Fetches one book or podcast including its metadata, tags and the listening progress of the API key’s user. Chapters, audio files and tracks are not part of the compact projection — use get_item_chapters for chapters, or detail="full" for everything.

Inputs: library_item_id (required), detail. Returns: source, truncated, untrusted

get_library_statsGet library statsA
Read-onlyIdempotent

Statistics for one library: number of items, authors and genres, total duration and size, longest and largest items.

Inputs: library_id (required). Returns: source, truncated, untrusted

get_listening_statsGet listening statsA
Read-onlyIdempotent

Aggregated listening statistics of the current user: total time, time per weekday, the last 30 days, the ten most listened items and the ten most recent sessions. detail="full" returns the complete per-day history and the full metadata of every item ever listened to, which is the largest response this API produces.

Inputs: detail. Returns: source, truncated, untrusted

get_meGet the current userA
Read-onlyIdempotent

Returns the Audiobookshelf user the API key acts on behalf of, with their permissions and accessible libraries. The compact projection reports media progress and bookmarks as counts — the full user object embeds every single one of them. Credential fields are removed from both projections.

Inputs: detail. Returns: source, truncated, untrusted, credentials_removed

get_media_progressGet media progressA
Read-onlyIdempotent

The listening progress of the current user for one book or podcast episode: position, percentage and whether it is finished. Returns a 404 error when the item has never been started.

Inputs: library_item_id (required), detail, episode_id. Returns: truncated

get_personalized_shelvesGet personalized shelvesA
Read-onlyIdempotent

The shelves of the Audiobookshelf home screen for this user: Continue Listening, Continue Series, Recently Added, Newest Episodes, Listen Again and so on. The fastest answer to "what am I listening to right now?".

Inputs: library_id (required), limit, detail. Returns: items, source, truncated, untrusted

get_playlistGet playlistA
Read-onlyIdempotent

Fetches one playlist with its entries, in order.

Inputs: playlist_id (required), detail. Returns: source, truncated, untrusted

get_podcast_episodeGet podcast episodeA
Read-onlyIdempotent

Fetches one podcast episode with its publication date, duration and description.

Inputs: episode_id (required), library_item_id (required), detail. Returns: source, truncated, untrusted

get_seriesGet seriesA
Read-onlyIdempotent

Fetches a single series by id, including its books. To list the books with paging and sorting, use list_library_items with filter_group="series" instead.

Inputs: series_id (required), detail. Returns: source, truncated, untrusted

get_server_statusGet server statusA
Read-onlyIdempotent

Version and initialization state of the Audiobookshelf server. Useful to check connectivity and whether the server is new enough for API keys (2.26.0 or later).

Inputs: no named parameters. Returns: truncated

get_year_statsGet stats for a yearB
Read-onlyIdempotent

The "year in review" statistics of the current user for one calendar year: books finished, time listened, top authors and genres.

Inputs: year (required). Returns: source, truncated, untrusted

list_authorsList authorsA
Read-onlyIdempotent

Lists all authors of a book library with their number of books. To list the books of one author, call list_library_items with filter_group="authors" and filter_value=.

Inputs: library_id (required), detail. Returns: source, authors, truncated, untrusted, +1 more

list_bookmarksList bookmarksA
Read-onlyIdempotent

The bookmarks of the current user — either all of them, or those of one library item. A bookmark is a named position in seconds.

Audiobookshelf has no bookmarks endpoint: they are a field on the account, so this reads /api/me and filters here. That is why there is no pagination — you get all of them.

Inputs: detail, library_item_id. Returns: source, bookmarks, truncated, untrusted

list_collectionsList collectionsA
Read-onlyIdempotent

Lists collections — the curated, ordered groups of books. Without library_id it returns the collections of every accessible library. Collections are shared server-wide; playlists are private per user.

Inputs: detail, library_id. Returns: source, truncated, untrusted, collections

list_genresList genresA
Read-onlyIdempotent

Lists all genres used on the server, across libraries. Genres come from the media metadata, not from the user.

Inputs: no named parameters. Returns: source, truncated, untrusted

list_items_in_progressList items in progressA
Read-onlyIdempotent

The items the user has started but not finished, newest first — the "Continue Listening" list across all libraries. The entries carry progressLastUpdate but not the position itself; use get_media_progress for that. For podcasts, recentEpisode names the episode in progress.

Inputs: limit, detail. Returns: source, truncated, untrusted, numReturned, +1 more

list_librariesList librariesA
Read-onlyIdempotent

Lists the Audiobookshelf libraries the API key’s user can access, with their id, name and media type (book or podcast). Start here — every other library tool needs a library id.

Inputs: detail. Returns: libraries, truncated

list_library_itemsList library itemsA
Read-onlyIdempotent

Lists items (books or podcasts) of a library, paginated, sortable and filterable. Use get_library_filter_data first to learn the valid filter values. Filter groups — valued (need filter_value): genres, tags, series, authors, progress, narrators, publishers, publishedDecades, missing, languages, tracks, ebooks; standalone: issues, feed-open, share-open, recent.

Inputs: library_id (required), page, sort, limit, +5 more. Returns: note, page, limit, total, +4 more

list_listening_sessionsList listening sessionsA
Read-onlyIdempotent

The playback sessions of the current user, newest first — each entry is one listening stretch with device, position and time listened.

Inputs: page, limit, detail. Returns: source, sessions, truncated, untrusted

list_playlistsList playlistsA
Read-onlyIdempotent

Lists the playlists of the API key’s user. Without library_id it returns the playlists of every accessible library. Playlists are private per user and can hold books or podcast episodes; collections are shared server-wide and hold books only.

Inputs: detail, library_id. Returns: source, playlists, truncated, untrusted

list_recent_episodesList recent podcast episodesA
Read-onlyIdempotent

Lists the most recently published episodes across a podcast library — the "Newest Episodes" view. Only works on libraries with mediaType "podcast".

Inputs: library_id (required), page, limit, detail. Returns: source, truncated, untrusted

list_seriesList seriesA
Read-onlyIdempotent

Lists the series of a book library with their number of books and total duration. To list the books of one series, call list_library_items with filter_group="series" and filter_value=.

Inputs: library_id (required), page, sort, limit, +2 more. Returns: page, limit, total, source, +3 more

list_tagsList tagsA
Read-onlyIdempotent

Lists all tags used on the server, across libraries. Tags are the user-defined labels on library items.

Inputs: no named parameters. Returns: source, truncated, untrusted

remove_books_from_collectionRemove books from collectionA
DestructiveIdempotent

Removes books from a collection. The books themselves are untouched — only their membership in the collection ends, and it can be restored with add_books_to_collection. Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it.

Inputs: collection_id (required), library_item_ids (required), confirm_token. Returns: source, truncated, untrusted

remove_items_from_playlistRemove items from playlistA
DestructiveIdempotent

Removes entries from a playlist. The media itself is untouched and the entries can be added back with add_items_to_playlist. Note that Audiobookshelf deletes a playlist automatically once its last entry is removed. Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it.

Inputs: items (required), playlist_id (required), confirm_token. Returns: source, truncated, untrusted

search_librarySearch a libraryA
Read-onlyIdempotent

Full-text search within one library. Matches books, podcasts, series, authors, narrators and tags. Use this for "do I own X?" questions; use list_library_items with a filter for "show me all X" questions.

Inputs: q (required), library_id (required), limit, detail. Returns: source, truncated, untrusted

set_media_progressSet media progressA
Idempotent

Creates or updates the listening progress of the API key’s user for one book or podcast episode. Set is_finished=true to mark it as finished, is_finished=false to reopen it (which resets the position to 0), or current_time to jump to a position in seconds. Audiobookshelf also marks an item finished on its own once less than ten seconds remain.

Inputs: library_item_id (required), progress, episode_id, is_finished, +2 more. Returns: source, updated, progress, truncated, +1 more

update_bookmarkUpdate bookmarkA
DestructiveIdempotent

Renames the bookmark at a given position. The position itself cannot be changed — delete the bookmark and create a new one for that.

Inputs: time (required), title (required), library_item_id (required). Returns: source, updated, bookmark, truncated, +1 more

update_collectionUpdate collectionA
DestructiveIdempotent

Renames a collection, changes its description or reorders its books.

library_item_ids ONLY REORDERS. It cannot add or remove anything: Audiobookshelf sorts the books the collection already has by their position in this list, so an id that is not currently in the collection is ignored, and a book you leave out is not removed — it moves to the FRONT. Pass every current book, in the order you want. Use add_books_to_collection and remove_books_from_collection to change membership.

Reordering asks a person first, because the order somebody arranged cannot be reconstructed afterwards; renaming and re-describing do not. Where the client cannot show a dialog, call once to receive a token and again with it.

Inputs: collection_id (required), name, description, confirm_token, +1 more. Returns: source, truncated, untrusted

update_playlistUpdate playlistA
DestructiveIdempotent

Renames a playlist, changes its description or reorders its entries.

items ONLY REORDERS. It cannot add or remove anything, and it must contain EXACTLY the entries the playlist already has: Audiobookshelf refuses a list of a different length with HTTP 400 "Invalid playlist items. Length mismatch". Read the current entries with get_playlist first, then send them in the order you want. Use add_items_to_playlist and remove_items_from_playlist to change membership. The library of a playlist cannot be changed.

Reordering asks a person first, because the order somebody arranged cannot be reconstructed afterwards; renaming and re-describing do not. Where the client cannot show a dialog, call once to receive a token and again with it.

Inputs: playlist_id (required), name, items, description, +1 more. Returns: source, truncated, untrusted

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 44 tools

    Disambiguation5/5

    Each tool maps to a distinct resource/action pair; list/get/set/delete/create/update/add/remove are consistently paired with a specific noun, and descriptions clarify near neighbours like get_library vs get_library_item and collections vs playlists.

    Naming Consistency5/5

    Names follow a uniform lowercase snake_case verb_noun pattern, with plural list_* for collections and singular get_* for single resources; exceptions like set_media_progress and get_me still fit the convention.

    Tool Count2/5

    44 tools is well above the 25+ threshold for a typical MCP surface; although each tool has a narrow role, the set is large and could be consolidated without losing clarity.

    Completeness5/5

    The surface covers browsing libraries/items/people/metadata, user progress, bookmarks, and full CRUD plus membership reordering for collections and playlists, with no obvious dead ends for the declared scope.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers