ni-c/audiobookshelf-mcp

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.
is resolved against the colour scheme of the page showing it, so GitHub
picks the variant that matches its own theme toggle. npm strips and
when it sanitises the README and keeps the , which is why that
fallback brings its own dark card instead of relying on a media query. -->
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.
Requirements
- Node.js 22 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.
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 Desktop