Audiobookshelf MCP Server
Provides tools for interacting with a self-hosted Audiobookshelf library: searching and browsing books by title, author, series, genre, narrator, and tags; reading listening history, progress, and stats; building taste profiles; checking whether books are already owned; and optionally making changes such as marking books finished, creating collections and playlists, and triggering library scans.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Audiobookshelf MCP Server recommend my next audiobook based on my listening history"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Audiobookshelf MCP Server
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
Sign in to Audiobookshelf as an admin.
Go to Settings → API Keys → Add API Key.
Give it a name (e.g.
Claude), choose the user it acts as, and optionally an expiry.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-serverOther 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 buildThen 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 --helpDocker / 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:latestMCP endpoint:
http://<host>:3000/mcp. Clients must sendAuthorization: Bearer <MCP_HTTP_AUTH_TOKEN>.Health check:
GET /healthz(no auth).Unless the server binds to localhost only,
MCP_HTTP_AUTH_TOKENis 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_HOSTSto 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 |
| required | Base URL of Audiobookshelf, e.g. |
| required¹ | API key (or legacy user token). |
| Path to a file containing the key, e.g. a Docker secret. Used if | |
| Alias for | |
| (all) | Comma-separated library IDs or names this server may use. Everything else is invisible to the assistant. |
| (first audiobook library) | Library ID or name used when a tool call doesn't specify one. |
|
|
|
|
| Per-request timeout to Audiobookshelf. |
|
| Upper limit on the number of results any single call can request. Keeps responses within the model's context. |
|
| Book descriptions are truncated to this length; |
|
| A book you've started but not touched for this many days counts as stalled. |
|
| How long libraries, progress and stats are cached in memory. |
|
|
|
|
|
|
|
| Bind address for HTTP mode (the Docker image uses |
|
| Port for HTTP mode. |
|
| Endpoint path for HTTP mode. |
| Bearer token clients must send. Required when the host isn't loopback. | |
| Comma-separated |
¹ 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 |
| Connection check: server version, the user the key acts as, allowed libraries, default library, whether write tools are on. |
| Allowed libraries with book/author/series counts. |
| Full-text search across titles, authors, series, narrators, genres and tags, with your progress on each hit. |
| Browse with one filter (author, series, genre, tag, narrator, language, publisher, progress, recently added) plus sort and paging. |
| Full details for one book: authors, narrators, series and position, genres, description, length, progress, and optionally chapters. |
| Authors by book count; one author's books grouped by series, with your status on each. |
| Series list; one series in reading order with the next unfinished book and any gaps in what you own. |
| The exact genres, tags, narrators, languages and publishers used in a library. |
| Your finished / in-progress / stalled books, most recent activity first. |
| Listening hours (today, 7/30/365 days, all time), by weekday, most-listened books, and recent sessions. Pass |
| Individual sessions: book, date, minutes, device. |
| The recommendation tool. See below. |
| Pass up to 50 |
| 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 |
| Mark books finished / not finished, e.g. books you listened to elsewhere. |
| Collections are shared with everyone who can see the library, and need the update permission. |
| Playlists are personal to the key's user. |
| 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:
abs_get_taste_profileto understand your tastethe assistant drafts candidates
abs_check_owneddrops the ones you already haveyou pick, and the assistant sends the requests through your downloader's tools
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_IDShides 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
Authorizationheader toABS_URLand is redacted from logs. PreferABS_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 |
| The key is wrong, expired or deactivated, or the user is disabled. Create a new key. |
| The key's user lacks the permission (e.g. scans need admin, collections need update). |
| Check that |
HTTPS with a self-signed certificate | Start Node with |
| The error lists the libraries available. Check |
Progress looks stale | Results are cached for |
Claude Desktop shows the server as failed | Check its MCP log ( |
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
Available Tools
17 toolsabs_check_ownedCheck which books are already ownedARead-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 authorBRead-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 detailsBRead-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…BRead-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 progressARead-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 sessionsBRead-onlyIdempotent
Individual listening sessions (newest first): what was played, when, for how long, on which device.
Inputs: page, limit.
abs_get_listening_statsListening statsARead-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 seriesARead-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 infoARead-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)ARead-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 authorsCRead-onlyIdempotent
List authors in a library with how many books of theirs it holds.
Inputs: page, sort, limit, library.
abs_list_collectionsList collectionsCRead-onlyIdempotent
Collections in a library (shared, curated lists) with their books.
Inputs: library.
abs_list_librariesList librariesARead-onlyIdempotent
List the Audiobookshelf libraries this server can use, with item counts.
Inputs: no named parameters.
abs_list_library_itemsBrowse library itemsARead-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 playlistsBRead-onlyIdempotent
The API key user's playlists (personal, ordered lists) across allowed libraries.
Inputs: no named parameters.
abs_list_seriesList seriesBRead-onlyIdempotent
List series in a library with the number of books held for each.
Inputs: page, sort, limit, library.
abs_search_librarySearch libraryARead-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
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
The media memory layer for AI agents and their humans. Your AI client can search your collection, add and log what you've finished, update ratings and lists, and find patterns across everything you've read, watched, played, and listened to.
AI assistant integration for Leaf — track books, log reading sessions, and manage your library.
Read and update your Hardcover library, progress, lists, and goals. Sign in with Hardcover OAuth.
Academic literature search, retrieval, and private library management on top of OpenAlex.
Related MCP Servers
- AlicenseAqualityBmaintenanceConnects AI assistants to the Hardcover book library, enabling natural language book searches, reading status updates, list management, and library exploration.28143 PyPI10MIT
- FlicenseAqualityDmaintenanceEnables AI assistants to interact with BookLore self-hosted libraries, allowing natural language queries to search books, manage reading status, ratings, series, authors, and highlights.71-
- AlicenseNot gradedqualityDmaintenanceEnables read-only search, browsing, and metadata retrieval from a local Calibre e-book library using natural language queries.MIT
- AlicenseNot gradedqualityBmaintenanceConnects 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