audiobookshelf-mcp

# audiobookshelf-mcp

[![CI](https://img.shields.io/github/actions/workflow/status/ni-c/audiobookshelf-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/audiobookshelf-mcp/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/audiobookshelf-mcp)](https://www.npmjs.com/package/audiobookshelf-mcp)
[![npm downloads](https://img.shields.io/npm/dm/audiobookshelf-mcp)](https://www.npmjs.com/package/audiobookshelf-mcp)
[![node](https://img.shields.io/node/v/audiobookshelf-mcp)](https://nodejs.org)
[![Container](https://img.shields.io/badge/ghcr.io-ni--c%2Faudiobookshelf--mcp-2496ED?logo=docker&logoColor=white)](https://github.com/ni-c/audiobookshelf-mcp/pkgs/container/audiobookshelf-mcp)
[![license](https://img.shields.io/npm/l/audiobookshelf-mcp)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-audiobookshelf--mcp.ni--c.de-4f46e5)](https://audiobookshelf-mcp.ni-c.de)
[![Sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)

An [MCP](https://modelcontextprotocol.io) server for
[Audiobookshelf](https://www.audiobookshelf.org/), the self-hosted audiobook and
podcast server. It lets an AI assistant 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, 15 write.

📖 **Full documentation: <https://audiobookshelf-mcp.ni-c.de>**

<!-- <picture> is resolved against the colour scheme of the page showing it, so GitHub
     picks the variant that matches its own theme toggle. npm strips <picture> and
     <source> when it sanitises the README and keeps the <img>, which is why that
     fallback brings its own dark card instead of relying on a media query. -->
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://audiobookshelf-mcp.ni-c.de/architecture-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="https://audiobookshelf-mcp.ni-c.de/architecture-light.svg">
  <img src="https://audiobookshelf-mcp.ni-c.de/architecture.svg" alt="An MCP client talks to audiobookshelf-mcp over stdio; the server exposes 29 read and 15 write tools, compacts every response, and calls the Audiobookshelf REST API over HTTPS with a bearer API key" width="800">
</picture>

<img src="https://audiobookshelf-mcp.ni-c.de/demo.gif" alt="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" width="800">

## 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   |

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.

## Install

```sh
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`):

```json
{
  "mcpServers": {
    "audiobookshelf": {
      "command": "npx",
      "args": ["-y", "audiobookshelf-mcp"],
      "env": {
        "AUDIOBOOKSHELF_URL": "https://abs.example.com",
        "AUDIOBOOKSHELF_API_KEY": "…"
      }
    }
  }
}
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.audiobookshelf]
command = "npx"
args = ["-y", "audiobookshelf-mcp"]
env = { AUDIOBOOKSHELF_URL = "https://abs.example.com", AUDIOBOOKSHELF_API_KEY = "…" }
```

Container (multi-arch, with SBOM and build provenance):

```sh
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](https://audiobookshelf-mcp.ni-c.de/guide/clients).

## Tools

### Reading

| Tool                                  | What it does                                                                                        |
| ------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `list_libraries`                      | The accessible libraries with id, name and media type — the entry point                             |
| `get_library`                         | One library with its folders and settings                                                           |
| `get_library_stats`                   | Item, author and genre counts, total duration and size                                              |
| `get_library_filter_data`             | The filterable values of a library: authors, genres, tags, series, narrators, languages, publishers |
| `list_library_items`                  | Items of a library, paginated, sortable, filterable                                                 |
| `search_library`                      | Full-text search across books, podcasts, series, authors, narrators and tags                        |
| `get_personalized_shelves`            | The home screen shelves: Continue Listening, Recently Added, …                                      |
| `list_series` / `get_series`          | Series with book count and total duration                                                           |
| `list_authors` / `get_author`         | Authors, optionally with their items                                                                |
| `list_tags` / `list_genres`           | All tags / genres used on the server                                                                |
| `get_library_item`                    | One book or podcast with metadata, tags and your progress                                           |
| `get_item_chapters`                   | The chapter list of a book, separate because it can be long                                         |
| `get_podcast_episode`                 | One episode with publication date, duration and description                                         |
| `list_recent_episodes`                | Newest episodes of a podcast library                                                                |
| `get_me`                              | The user the API key acts for, with permissions and libraries                                       |
| `list_items_in_progress`              | Started but unfinished items across all libraries                                                   |
| `get_media_progress`                  | Position, percentage and finished state for one item                                                |
| `get_listening_stats`                 | Total time, time per day and per weekday, most listened items                                       |
| `get_year_stats`                      | The "year in review" figures for one calendar year                                                  |
| `list_listening_sessions`             | Playback sessions with device, position and time listened                                           |
| `list_bookmarks`                      | Bookmarks, all of them or those of one item                                                         |
| `list_collections` / `get_collection` | Collections — shared, ordered groups of books                                                       |
| `list_playlists` / `get_playlist`     | Playlists — private per user, books or episodes                                                     |
| `get_server_status`                   | Version and initialization state of the server                                                      |

### Writing

| Tool                                                            | What it does                                                            |
| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `set_media_progress`                                            | Set position, mark finished or unfinished, hide from Continue Listening |
| `delete_media_progress`                                         | Delete a progress record — needs a confirmation token                   |
| `create_bookmark` / `update_bookmark` / `delete_bookmark`       | Named positions in a book                                               |
| `create_collection` / `update_collection` / `delete_collection` | Collections; delete needs a confirmation token                          |
|