Skip to main content
Glama
Audiobookshelf MCP Server

Audiobookshelf MCP Server

Audiobookshelf MCP Server

CI npm License: MIT

A Model Context Protocol server that lets an AI assistant (Claude, or any MCP client) work with your self-hosted Audiobookshelf library. It can:

  • search and browse your library by title, author, series, genre, narrator, tag and more

  • read your listening history: what you've finished, what's in progress, what you've abandoned, and how long you listen

  • build a taste profile in a single call, so the assistant can recommend books that suit you

  • check whether you already own a book, fuzzy-matching titles from a list of candidates

  • optionally make changes: mark books finished, build collections and playlists, trigger library scans

It is read-only by default. The write tools only appear when you opt in.

You:     Based on what I've listened to, what should I get next?
Claude:  (calls abs_get_taste_profile, then abs_check_owned)
         You've finished both Stormlight books you own and Rhythm of War is waiting
         unread, but you're missing book 3, Oathbringer. You also own Mistborn and
         haven't started it. Here are five books you don't own yet that match what
         you tend to finish…

Not affiliated with the Audiobookshelf project.


Contents


Related MCP server: booklore-mcp

Requirements

  • Audiobookshelf v2.26.0 or newer. That release added API keys. Developed and tested against the v2.37 API.

  • Node.js 20+, or Docker.

  • An MCP client: Claude Desktop, Claude Code, or any other client that supports stdio or Streamable HTTP servers.

Quick start

1. Create an Audiobookshelf API key

  1. Sign in to Audiobookshelf as an admin.

  2. Go to Settings → API Keys → Add API Key.

  3. Give it a name (e.g. Claude), choose the user it acts as, and optionally an expiry.

  4. Copy the key. It is shown only once.

The key acts as the user you choose. Progress, history, stats and playlists are all that user's, and it only sees the libraries that user can access. To get recommendations from your history, pick your user. For least privilege, create a dedicated non-admin user with access to just the libraries you want to share, and leave write tools off.

On an older server, or if you'd rather not use API keys, the legacy per-user token (Settings → Users → your user → API token) also works. Audiobookshelf has deprecated those tokens, though.

2. Add the server to your MCP client

Claude Desktop

Open Settings → Developer → Edit Config (or edit claude_desktop_config.json directly) and add:

{
  "mcpServers": {
    "audiobookshelf": {
      "command": "npx",
      "args": ["-y", "audiobookshelf-mcp-server"],
      "env": {
        "ABS_URL": "http://192.168.1.10:13378",
        "ABS_API_KEY": "paste-your-key-here"
      }
    }
  }
}

Restart Claude Desktop. Then ask: "Check my Audiobookshelf connection". The assistant should call abs_get_server_info and report your username and libraries.

Config file locations: macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json.

Claude Code

claude mcp add audiobookshelf \
  -e ABS_URL=http://192.168.1.10:13378 \
  -e ABS_API_KEY=paste-your-key-here \
  -- npx -y audiobookshelf-mcp-server

Other clients

Any client that can launch a stdio server can use the same command (npx -y audiobookshelf-mcp-server) with the same environment variables. For clients that connect over HTTP, see Docker / HTTP.

Other ways to run it

From source

git clone https://github.com/BiffstaGaming/audiobookshelf-mcp-server.git
cd audiobookshelf-mcp-server
npm ci && npm run build

Then point your client at node /absolute/path/to/audiobookshelf-mcp-server/dist/index.js instead of npx.

Global install

npm install -g audiobookshelf-mcp-server
audiobookshelf-mcp-server --help

Docker / HTTP

The container runs the Streamable HTTP transport on port 3000. This suits a home server, a NAS, or a machine that isn't running your MCP client.

docker run -d --name audiobookshelf-mcp -p 3000:3000 \
  -e ABS_URL=http://audiobookshelf:13378 \
  -e ABS_API_KEY=paste-your-key-here \
  -e MCP_HTTP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  ghcr.io/biffstagaming/audiobookshelf-mcp-server:latest
  • MCP endpoint: http://<host>:3000/mcp. Clients must send Authorization: Bearer <MCP_HTTP_AUTH_TOKEN>.

  • Health check: GET /healthz (no auth).

  • Unless the server binds to localhost only, MCP_HTTP_AUTH_TOKEN is required and the server will refuse to start without it.

  • For anything reachable from outside your network, put it behind a TLS-terminating reverse proxy and set MCP_HTTP_ALLOWED_HOSTS to your hostname(s) to enable DNS-rebinding protection.

There is a docker-compose.example.yml and an .env.example to start from. Without Docker, set MCP_TRANSPORT=http to get the same HTTP mode.

Configuration

Everything is configured through environment variables. Invalid values stop the server at startup with a message naming the variable.

Variable

Default

Description

ABS_URL

required

Base URL of Audiobookshelf, e.g. http://192.168.1.10:13378 or https://example.com/audiobookshelf (reverse-proxy sub-paths are supported).

ABS_API_KEY

required¹

API key (or legacy user token).

ABS_API_KEY_FILE

Path to a file containing the key, e.g. a Docker secret. Used if ABS_API_KEY is unset.

ABS_TOKEN

Alias for ABS_API_KEY.

ABS_LIBRARY_IDS

(all)

Comma-separated library IDs or names this server may use. Everything else is invisible to the assistant.

ABS_DEFAULT_LIBRARY

(first audiobook library)

Library ID or name used when a tool call doesn't specify one.

ABS_ENABLE_WRITE_TOOLS

false

true registers the write tools.

ABS_REQUEST_TIMEOUT_MS

30000

Per-request timeout to Audiobookshelf.

ABS_MAX_RESULTS

50

Upper limit on the number of results any single call can request. Keeps responses within the model's context.

ABS_DESCRIPTION_MAX_CHARS

300

Book descriptions are truncated to this length; 0 omits them. (abs_get_item can return the full text.)

ABS_STALLED_AFTER_DAYS

60

A book you've started but not touched for this many days counts as stalled.

ABS_CACHE_TTL_SECONDS

60

How long libraries, progress and stats are cached in memory. 0 disables caching. Write tools clear the cache entries they affect.

LOG_LEVEL

info

error, warn, info or debug. Logs go to stderr with secrets redacted.

MCP_TRANSPORT

stdio

stdio or http.

MCP_HTTP_HOST

127.0.0.1

Bind address for HTTP mode (the Docker image uses 0.0.0.0).

MCP_HTTP_PORT

3000

Port for HTTP mode.

MCP_HTTP_PATH

/mcp

Endpoint path for HTTP mode.

MCP_HTTP_AUTH_TOKEN

Bearer token clients must send. Required when the host isn't loopback.

MCP_HTTP_ALLOWED_HOSTS

Comma-separated Host header values to accept (turns on DNS-rebinding protection).

¹ Either ABS_API_KEY, ABS_TOKEN or ABS_API_KEY_FILE.

Running from source, you can keep the settings in a .env file and use node --env-file=.env dist/index.js.

Tools

All tools return compact JSON designed for a language model. Raw Audiobookshelf objects (file lists, paths, tracks) are trimmed down. Where a tool takes a library, author or series argument, you can pass a name or an ID, matched case-insensitively. Ambiguous names return the candidates so the assistant can pick one.

Read tools (always on)

Tool

What it does

abs_get_server_info

Connection check: server version, the user the key acts as, allowed libraries, default library, whether write tools are on.

abs_list_libraries

Allowed libraries with book/author/series counts.

abs_search_library

Full-text search across titles, authors, series, narrators, genres and tags, with your progress on each hit.

abs_list_library_items

Browse with one filter (author, series, genre, tag, narrator, language, publisher, progress, recently added) plus sort and paging.

abs_get_item

Full details for one book: authors, narrators, series and position, genres, description, length, progress, and optionally chapters.

abs_list_authors / abs_get_author

Authors by book count; one author's books grouped by series, with your status on each.

abs_list_series / abs_get_series

Series list; one series in reading order with the next unfinished book and any gaps in what you own.

abs_get_library_facets

The exact genres, tags, narrators, languages and publishers used in a library.

abs_get_listening_progress

Your finished / in-progress / stalled books, most recent activity first.

abs_get_listening_stats

Listening hours (today, 7/30/365 days, all time), by weekday, most-listened books, and recent sessions. Pass year for Audiobookshelf's year-in-review stats.

abs_get_listening_sessions

Individual sessions: book, date, minutes, device.

abs_get_taste_profile

The recommendation tool. See below.

abs_check_owned

Pass up to 50 {title, author} candidates. For each, it reports whether you own it (exact / likely / possible match) and whether you've listened to it.

abs_list_collections / abs_list_playlists

Collections in a library; your playlists.

Write tools (opt-in)

These are registered only when ABS_ENABLE_WRITE_TOOLS=true. None of them delete anything. Each one is still subject to the Audiobookshelf permissions of the key's user.

Tool

What it does

abs_set_finished

Mark books finished / not finished, e.g. books you listened to elsewhere.

abs_create_collection / abs_add_to_collection

Collections are shared with everyone who can see the library, and need the update permission.

abs_create_playlist / abs_add_to_playlist

Playlists are personal to the key's user.

abs_scan_library

Start a library scan, e.g. after a download lands. Admin only.

Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint), so clients can auto-approve the read tools and still ask before writes.

Prompts

The server ships two prompt templates. Clients that support MCP prompts show them as slash commands.

  • recommend_audiobooks (count, mood): profile your taste, draft candidates, drop the ones you already own, and explain each pick. It won't download anything without asking.

  • continue_my_series: for each series you've started, the next book you own and the next one you don't.

How the taste profile works

abs_get_taste_profile gathers everything a recommendation needs in one call, so the assistant doesn't spend twenty tool calls (and its context) assembling it:

  • Rankings of authors, series, genres, narrators, tags, languages, publication decades and book lengths. Each is scored by engagement: a finished book counts 1.0; an in-progress book 0.6 and a stalled one 0.15, each scaled by how far through you got (minimum 25%). Each entry also shows finished / in-progress / stalled counts and hours listened.

  • Totals: books finished, in progress and stalled; listening hours (30 days, 365 days, all time); the median length of the books you finish.

  • Recently finished, currently listening and stalled lists.

  • Series status for your most-engaged series: books owned and finished, the next owned book you haven't finished, and whole-number gaps in what you own (own 1, 2, 4 → missing 3).

  • Unread books by your top authors that are already in the library.

Audiobookshelf only knows about books that are in your library. It can't tell you that book 5 of a series exists. The assistant supplies that from its own knowledge, and abs_check_owned confirms what you already have.

Recommend-then-download workflows

This server deliberately doesn't download anything; acquiring books depends on your own setup. MCP clients can connect several servers at once, though, so the assistant can combine this one with whatever you use to request books: a Home Assistant integration, an *arr-style app, or your own tool. A typical flow:

  1. abs_get_taste_profile to understand your taste

  2. the assistant drafts candidates

  3. abs_check_owned drops the ones you already have

  4. you pick, and the assistant sends the requests through your downloader's tools

  5. optionally abs_scan_library (write tools on) once the files land, if your library doesn't watch for new files

Security and privacy

  • Your data stays on your network. The server talks only to your Audiobookshelf server, plus whatever MCP client you connect it to. There's no telemetry. Bear in mind that whatever the tools return is sent to the model behind your client.

  • Least privilege. Read-only by default. ABS_LIBRARY_IDS hides libraries entirely: their items aren't returned or counted, even when Audiobookshelf would allow it. For tighter limits, give the key a non-admin user.

  • Secrets. The key is sent only in the Authorization header to ABS_URL and is redacted from logs. Prefer ABS_API_KEY_FILE (Docker secrets) over plain environment variables on shared hosts. Give API keys an expiry and rotate them.

  • HTTP mode requires a bearer token whenever it isn't bound to localhost (checked in constant time). Always put TLS in front of anything you expose.

Found a vulnerability? Please report it privately; see SECURITY.md.

Troubleshooting

Symptom

Fix

rejected the API key (401)

The key is wrong, expired or deactivated, or the user is disabled. Create a new key.

not allowed to do this (403)

The key's user lacks the permission (e.g. scans need admin, collections need update).

Could not reach Audiobookshelf

Check that ABS_URL is reachable from where the server runs. In Docker, localhost means the container itself, so use the host's IP or the compose service name.

HTTPS with a self-signed certificate

Start Node with NODE_EXTRA_CA_CERTS=/path/to/ca.pem. Don't disable TLS verification.

Library "X" not found or not allowed

The error lists the libraries available. Check ABS_LIBRARY_IDS / ABS_DEFAULT_LIBRARY.

Progress looks stale

Results are cached for ABS_CACHE_TTL_SECONDS (default 60 s).

Claude Desktop shows the server as failed

Check its MCP log (mcp-server-audiobookshelf.log). Configuration errors are printed there on startup. Set LOG_LEVEL=debug for request-level detail.

Podcast libraries can be searched and browsed, but the history and recommendation tools only cover books.

Development

npm ci
npm run dev          # run from source (tsx)
npm test             # vitest: unit tests + full MCP round-trips against a fake Audiobookshelf
npm run check        # typecheck + lint + format check + tests
npm run build        # compile to dist/

The tests run every tool through a real MCP client, over both the in-memory and Streamable HTTP transports, against a fake Audiobookshelf (test/fake-abs.ts). The fake's responses are modelled on the Audiobookshelf server source. API shapes and endpoint notes live in src/abs/.

Releasing: bump version in package.json, update CHANGELOG.md, then push a vX.Y.Z tag. The release workflow publishes to npm (needs the NPM_TOKEN repository secret) and pushes a multi-arch image to GHCR.

Contributions are welcome; see CONTRIBUTING.md.

License

MIT

Available Tools

17 tools
abs_check_ownedCheck which books are already ownedA
Read-onlyIdempotent

Given candidate books (title + optional author), report which are already in the library and whether the user has listened to them. Tolerates subtitles, leading articles, punctuation and "(Unabridged)". confidence: exact | likely | possible. Use to filter recommendations before requesting downloads.

Inputs: books (required), library.

abs_get_authorGet authorB
Read-onlyIdempotent

An author's books in the library, grouped by series, each with your progress. Accepts a name or ID.

Inputs: author (required), library.

abs_get_itemGet item detailsB
Read-onlyIdempotent

Full details for one library item: authors, narrators, series with sequence, genres, tags, description, length, and your progress. Optionally the chapter list.

Inputs: item_id (required), full_description, include_chapters.

abs_get_library_facetsGenres, tags, narrators…B
Read-onlyIdempotent

The distinct genres, tags, narrators, languages and publishers present in a library — useful for exact filter values and for describing the collection.

Inputs: facets, library.

abs_get_listening_progressMy progressA
Read-onlyIdempotent

Books the API key user has started or finished, newest activity first. "stalled" = started but untouched for longer than ABS_STALLED_AFTER_DAYS.

Inputs: page, limit, status, library.

abs_get_listening_sessionsListening sessionsB
Read-onlyIdempotent

Individual listening sessions (newest first): what was played, when, for how long, on which device.

Inputs: page, limit.

abs_get_listening_statsListening statsA
Read-onlyIdempotent

Listening time totals (all time, last 7/30/365 days), by weekday, most-listened items, and recent sessions. Pass year for that year’s Audiobookshelf "year in review" stats.

Inputs: year, top_items.

abs_get_seriesGet seriesA
Read-onlyIdempotent

Books of one series that are in the library, in reading order, with your status for each, the next unfinished one, and whole-number gaps in the owned sequence (e.g. own 1, 2, 4 → missing 3). Books never added to the library are not known to Audiobookshelf.

Inputs: series (required), library.

abs_get_server_infoAudiobookshelf connection infoA
Read-onlyIdempotent

Check the connection and see who the API key belongs to, the server version, the libraries this server may use, and whether write tools are enabled. Call this first if other tools fail.

Inputs: no named parameters.

abs_get_taste_profileTaste profile (for recommendations)A
Read-onlyIdempotent

One-call summary of the user’s listening taste for making recommendations: top authors, series, genres, narrators and tags weighted by engagement; length and era preferences; recently finished, current and stalled books; per-series status (next owned unfinished book, gaps); and unread books already owned by favourite authors. Use before recommending, then verify candidates with abs_check_owned.

Inputs: top_n, library, max_series, max_authors, +2 more.

abs_list_authorsList authorsC
Read-onlyIdempotent

List authors in a library with how many books of theirs it holds.

Inputs: page, sort, limit, library.

abs_list_collectionsList collectionsC
Read-onlyIdempotent

Collections in a library (shared, curated lists) with their books.

Inputs: library.

abs_list_librariesList librariesA
Read-onlyIdempotent

List the Audiobookshelf libraries this server can use, with item counts.

Inputs: no named parameters.

abs_list_library_itemsBrowse library itemsA
Read-onlyIdempotent

Browse a library with ONE optional filter (author, series, genre, tag, narrator, language, publisher or your progress) plus sorting and paging. Names are matched case-insensitively. Use for "show me all X" questions.

Inputs: tag, page, sort, genre, +10 more.

abs_list_playlistsList playlistsB
Read-onlyIdempotent

The API key user's playlists (personal, ordered lists) across allowed libraries.

Inputs: no named parameters.

abs_list_seriesList seriesB
Read-onlyIdempotent

List series in a library with the number of books held for each.

Inputs: page, sort, limit, library.

abs_search_librarySearch libraryA
Read-onlyIdempotent

Full-text search of one library: matches book titles/subtitles, authors, series, narrators, genres and tags. Best for "do I have X?" or finding an ID. For checking many candidate titles at once use abs_check_owned.

Inputs: query (required), limit, library.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (browse vs. search vs. detail vs. owned-check), and descriptions explicitly steer between near-neighbours like abs_search_library vs abs_check_owned and abs_list_authors vs abs_get_author. The only mild overlap is the trio abs_get_listening_progress / abs_get_listening_stats / abs_get_listening_sessions, which all describe recent listening but at different granularities.

    Naming Consistency5/5

    All 17 tools use a uniform abs_ prefix plus snake_case verb_noun naming (abs_list_*, abs_get_*, abs_search_*, abs_check_*), with no camelCase or style mixing. Verb choices map predictably to actions, so naming gives strong cues about each tool's role.

    Tool Count4/5

    17 tools is just over the comfortable 3-15 band but each one covers a distinct slice of the Audiobookshelf domain (libraries, items, authors, series, collections, playlists, stats, recommendations). There is no obviously redundant or filler tool, so the count is justified rather than bloated.

    Completeness4/5

    The read/exploration surface is thorough: connection info, library browsing, search, facets, item/author/series details, collections, playlists, listening stats, taste profile and owned-check all exist. The notable gap is write operations — despite abs_get_server_info mentioning "write tools are enabled", the surfaced set contains no create/update/delete for playlists, collections or progress.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Connects AI assistants to the Hardcover book library, enabling natural language book searches, reading status updates, list management, and library exploration.
      28
      143 PyPI
      10
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to interact with BookLore self-hosted libraries, allowing natural language queries to search books, manage reading status, ratings, series, authors, and highlights.
      7
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only search, browsing, and metadata retrieval from a local Calibre e-book library using natural language queries.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects AI assistants to a local music library for full-text search and filtering of tracks, albums, artists, genres, composers, and lyrics, plus listening analytics and metadata hygiene audits. Also lets users generate and populate playlists and control playback (play, pause, seek, volume) in a running player instance.
      MIT