audiobookshelf-mcp

audiobookshelf-mcpYour audiobook library, in the conversation

An MCP server for Audiobookshelf. Browse your libraries, ask what you own and what you have listened to, and keep progress, bookmarks, collections and playlists in sync.

Get started
Tools reference
GitHub

  • 44 tools, 29 of them read-only

    Libraries, items, search, series, authors, chapters, podcast episodes, listening progress, statistics and sessions, bookmarks, collections and playlists — plus 15 write tools you can switch off entirely.

  • Built for a model's context

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

  • Register only the tools you need

    AUDIOBOOKSHELF_READ_ONLY=true registers the read tools and nothing else. AUDIOBOOKSHELF_ALLOW_TOOLS cuts finer — essential for a curated eight, your own comma-separated list, or a whole family with list_* — and AUDIOBOOKSHELF_DENY_TOOLS subtracts. Whatever is filtered out does not exist on the protocol rather than failing when called, and a name that matches no tool stops the server at startup instead of quietly going missing.

  • A person is asked, not just told

    The six tools that take something out ask a person first, through MCP elicitation — a dialog the model cannot answer on its behalf. Where the client cannot show one they fall back to a single-use token bound to the exact targets, and say which of the two it was rather than implying somebody approved. Upstream content is marked untrusted, and read-only mode simply does not register the write tools.

audiobookshelf-mcp architectureAn MCP client talks to audiobookshelf-mcp over stdio. The server exposes 29 read tools and 15 write tools, compacts every response, and calls the Audiobookshelf REST API over HTTPS with a bearer API key. Deleting requires a confirmation token.MCP clientClaude Code · DesktopCodex · Inspectorstdiono portaudiobookshelf-mcp29 read toolslibraries · items · progress · stats15 write toolsprogress · bookmarks · collectionsdeletes ask a person firstREAD_ONLY=truewrite tools are never registeredevery response compacted, lists cappedHTTPSbearer API keyno redirectsAudiobookshelf2.26.0 or neweryour self-hosted server
The server holds one Audiobookshelf API key and speaks stdio — it never listens on a port.

Terminal recording: the server reports 44 tools, lists library items as a compact projection, and answers the first delete_collection call with a single-use confirmation token instead of deleting anything

In one command ​

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

Then ask things like "what am I in the middle of?", "do I own anything by Frank Schätzing?", "how much did I listen to last month?" or "put the three unfinished ones in a playlist called Backlog".

What it does not 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 — even when the API key would permit them. See Security.

Running it elsewhere ​

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — cannot start audiobookshelf-mcp the way Claude Code does. mcp-hub is the bridge: 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 instead of ending at the gateway.

Its configuration is Claude Code's mcpServers format, so the entry you already have is the entry it takes: Through mcp-hub.

Released under the MIT License.

Copyright © 2026 Willi Thiel