Log inSubmit server
Audiobookshelf logo

Audiobookshelf

Browse Audiobookshelf libraries, inspect listening activity, and manage progress, bookmarks, collections, and playlists through MCP.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Audiobookshelf

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "audiobookshelf": {
      "command": "npx",
      "args": [
        "-y",
        "audiobookshelf-mcp"
      ],
      "env": {
        "AUDIOBOOKSHELF_URL": "YOUR_VALUE_HERE",
        "AUDIOBOOKSHELF_API_KEY": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

The Audiobookshelf MCP server connects MCP clients to a self-hosted Audiobookshelf instance through its REST API. It provides read tools for browsing libraries, searching media, inspecting metadata, and reviewing listening activity, plus write tools for progress, bookmarks, collections, and playlists. Use it when an agent needs access to a user's Audiobookshelf catalog or listening state. Node.js 22 or newer, Audiobookshelf 2.26.0 or newer, and an API key are required.

Use cases

  • Browse accessible audiobook and podcast libraries
  • Search for books, authors, series, or narrators
  • Review unfinished listening and playback statistics
  • Update progress and create bookmarks
  • Organize books and episodes into collections or playlists

Key features

  • Library browsing with filtering, sorting, and search
  • Audiobook, podcast, chapter, and metadata lookup
  • Listening progress, sessions, bookmarks, and statistics
  • Progress and completion updates
  • Collection and playlist management
  • Configurable read-only and tool filtering modes

Tools30

What Audiobookshelf lets your agent do. Expand a tool for its parameters.

Self-reported~486 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 3d ago

Recent health check succeeded.

7/7 checks healthy over the last 47d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 13d ago via OSV.dev · audiobookshelf-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars1Stargazers on the source repository.
npm downloads254Package downloads in the last 30 days.
Last commit4d agoMost recent push to the default branch.
Tools exposed30Callable tools this server registers over MCP.

How Audiobookshelf works

What the Audiobookshelf MCP server does

The Audiobookshelf MCP server gives an MCP client access to a user's Audiobookshelf libraries and listening data. It can enumerate libraries, inspect folders and statistics, search across books, podcasts, series, authors, narrators, and tags, and retrieve item metadata, chapters, episodes, and personal shelves.

It also covers listening activity. Agents can find unfinished items, inspect media position and completion state, review listening sessions, retrieve bookmarks, and read aggregate or yearly statistics. Write operations can update playback progress, create bookmarks, create collections and playlists, and add books or episodes to those groups.

How it works

The server runs as an MCP process and sends requests to the configured Audiobookshelf REST API over HTTPS. Authentication uses a bearer API key. That key represents one Audiobookshelf user, so visible libraries and permitted operations follow that user's permissions.

Responses use compact projections rather than returning every field in expanded media objects. The available tool set can be reduced with environment variables. Read-only mode registers only read tools, while allow and deny filters can select individual tools or tool families. The essential preset provides a smaller set for common browsing, search, and progress tasks.

Setup and configuration

Install the package with npx -y audiobookshelf-mcp, configure it as a local MCP process, or run the supplied container image with standard input attached. The protocol uses stdin and stdout; the Docker example does not require a published port. The README includes configuration examples for Claude Code, Claude Desktop, and Codex.

Required variables are:

  • AUDIOBOOKSHELF_URL: The base URL of the Audiobookshelf instance, without credentials.
  • AUDIOBOOKSHELF_API_KEY: An API key created by an administrator under Audiobookshelf user settings.

Optional settings include AUDIOBOOKSHELF_READ_ONLY, AUDIOBOOKSHELF_INSECURE_TLS, AUDIOBOOKSHELF_ALLOW_TOOLS, AUDIOBOOKSHELF_DENY_TOOLS, and ELICITATION. Self-signed TLS acceptance is scoped to the connection. Tool filters that match no tool cause startup to fail rather than silently changing the available set.

Tools and capabilities

The Audiobookshelf MCP server exposes tools for:

  • Listing libraries, series, authors, tags, collections, playlists, and recent podcast episodes.
  • Filtering and sorting library items, retrieving filter values, and performing full-text searches.
  • Reading item metadata, chapters, podcast episode details, user identity, permissions, and server status.
  • Reviewing progress, unfinished items, bookmarks, sessions, listening totals, and yearly statistics.
  • Setting playback position or finished state, hiding items from Continue Listening, and creating bookmarks.
  • Creating collections and playlists and adding books or episodes to them.

A read-only configuration prevents write tools from being registered. Some operations that change or remove data require user approval through MCP elicitation; when the client cannot display that dialog, the server can use a single-use confirmation token instead.

Limitations and notes

Audiobookshelf 2.26.0 or newer is required because earlier versions do not provide API keys. The API key is shown only once when created, and an ordinary user's key cannot access libraries or deletion operations beyond that user's permissions.

The server can start without configuration for MCP discovery, but calls then return setup instructions.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Audiobookshelf

Audiobookshelf is an MCP server that connects MCP clients to a self-hosted Audiobookshelf instance. Its main tools browse libraries, search books and podcasts, inspect metadata and listening progress, review bookmarks and statistics, and update progress, collections, playlists, and bookmarks for the API key's user.

Install it with `npx -y audiobookshelf-mcp` or run the provided container image. Configure `AUDIOBOOKSHELF_URL` and `AUDIOBOOKSHELF_API_KEY`, then register the process with an MCP client such as Claude Code, Claude Desktop, or Codex.

It requires `AUDIOBOOKSHELF_URL` and `AUDIOBOOKSHELF_API_KEY`. The URL identifies the Audiobookshelf instance, and the API key is sent as a bearer token. Read-only mode, TLS handling, tool allowlists, denylists, and elicitation behavior are optional.

Yes, through mcp-hub rather than by directly spawning the local stdio process.

Set `AUDIOBOOKSHELF_READ_ONLY=true`. The server then registers only its read tools, so write tools are absent from the available MCP tool list instead of being callable and rejected.

Related MCP servers

All in Developer Tools All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewAudiobookshelf AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/audiobookshelf?style=directory)](https://allmcps.com/mcp/audiobookshelf)
HTML Embed
<a href="https://allmcps.com/mcp/audiobookshelf"><img src="https://allmcps.com/api/badge/audiobookshelf?style=directory" alt="Audiobookshelf on AllMCPs" /></a>