Purpose
audiobookshelf-mcp is a Model Context Protocol (MCP) server for connecting to Audiobookshelf—a self-hosted audiobook and podcast server. It lets MCP clients (such as Claude Code, Claude Desktop, and Codex) browse media libraries, answer questions about what the user owns and has listened to, and keep listening progress, bookmarks, favorites, and playlists in sync.
Main capabilities
The server provides 44 tools in total, of which 29 are read-only and 15 are writable. The tool count is a ceiling, not a floor: with AUDIOBOOKSHELF_ALLOW_TOOLS=essential, only a curated set of 8 tools is registered (list_libraries, search_library, list_library_items, get_library_item, get_item_chapters, list_items_in_progress, get_media_progress, set_media_progress), and models usually choose more reliably from 8 tools than from 44.
Every response is a projection rather than a raw object. Expanded library items carry every audio file, track, and chapter along with complete ffprobe metadata, while media tools return a compact structure by default; pass detail="full" when the raw object is needed.
29 of the 44 tools are read-only. Setting AUDIOBOOKSHELF_READ_ONLY=true registers only these read-only tools, and write tools do not appear in tools/list rather than being rejected at call time.
The six tools that remove content first ask a human, via MCP elicitation, which pops up a dialog that the model cannot answer on the user's behalf; when the client cannot display a dialog, it falls back to a one-time token bound to the exact target.
Usage
Requirements: Node.js 22 or later; Audiobookshelf 2.26.0 or later (earlier versions do not have API keys); an Audiobookshelf API key.
Getting an API key: managed by an administrator under Settings → Users → API Keys. The key represents exactly oneAn Audiobookshelf user acts and inherits that user's permissions, so a key issued for an ordinary account cannot see libraries that account cannot see, nor can it delete content that account has no permission to delete. The key is shown only once at creation time.
The server can start without configuration: it completes the MCP handshake and lists tools, after which every call fails with setup instructions. This is intentional, so that registries and sandbox inspectors can introspect it.
Choose which tools to load: AUDIOBOOKSHELF_ALLOW_TOOLS and AUDIOBOOKSHELF_DENY_TOOLS accept comma-separated tool names, with a trailing * matching an entire tool family. essential is a curated preset of 8 tools. An entry that matches no tools causes startup to abort and points out that entry, so typos do not silently hide tools. Filtered tools are never registered, so they do not exist in tools/list, and tools/call does not recognize them either, exactly like write tools under AUDIOBOOKSHELF_READ_ONLY.
If you run several such servers at the same time, mcp-hub is another option—its /hub endpoint replaces each server's tools with six meta-tools.
Client configuration examples (claude_desktop_config.json, ~/.codex/config.toml, etc.) and Docker run instructions (-i is required, the protocol runs over stdin and stdout, there is no port to publish) are explained further in the client guide.
Via mcp-hub: clients that cannot spawn local processes (ChatGPT connectors, Claude on the web, Cursor, LibreChat) can access audiobookshelf-mcp through mcp-hub: a single container serves multiple stdio MCP servers over Streamable HTTP, with OAuth 2.1 login behind a single password, and long-lived tokens for clients that cannot do OAuth. Its /hub endpoint places all servers behind six meta-tools, so a single connector can access all servers without putting N×tool schemas in the model context, and it supports both protocol revisions.
When to use it
Suitable for those who want to query and manage a self-hosted AudioUsers of the bookshelf media library, for example browsing the media library, searching content, viewing listening progress and statistics, syncing bookmarks, favorites, and playlists.
Limitations
Features intentionally not exposed: no playback functionality (pause, seek, and play belong to the real client's session state machine; set_media_progress covers "mark as finished" and "jump to chapter 12", while playback is done by the phone); no administrative functionality, even with an admin key there are no tools for user management, server settings, backups, cache clearing, filesystem browsing, media library or item deletion, metadata rewriting, or file uploads.
Security design: read-only mode does not register write tools; the eight tools that may remove content (three deletions, delete_bookmark, remove_books_from_collection, remove_items_from_playlist, and update_collection / update_playlist when reordering is requested) pop up a human confirmation dialog via MCP elicitation; confirmation prompts never reference API content, listing only ids and counts; a 200 response that is not JSON is treated as an error; untrusted content is flagged; the API key is removed from the environment after the configuration is read; redirects are not followed, and each request has a 15-second timeout; ids are validated before entering URL paths; upstream error bodies are sanitized; progress updates send only whitelisted fields.
One caveat from Audiobookshelf itself: removing the last item from a playlist deletes that playlist, and remove_items_from_playlist states this in the result when it happens.
Response size limits: 5 MB response cap (content-length is checked before reading, and chunked bodies are counted as they are read); 100,000-byte result cap (applied in jsonResult, overriding detail="full", discarding the entire result rather than truncating characters); embedded member cap (compact collections or playlists embed the first 25 books or items and report the true count, while get_collection and get_playlist return the full members of one of them). list_library_items supports limit and page pagination; the seven list tools have no pagination parameters because the Audiobookshelf routes behind them returnall content at once and do not accept pagination parameters.
The full guide, tool reference, and security notes are at audiobookshelf-mcp.ni-c.de (source in docs/). The project is licensed under MIT.
