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.

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

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.