audiobookshelf
Provides tools for interacting with a self-hosted Audiobookshelf server's HTTP API, enabling management of libraries, items, collections, playlists, authors, series, podcasts, search, sessions, stats, tags, genres, users, admin settings, backups, and related resources, with read/write controls and confirmation for writes.
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 list my audiobook libraries"
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 connector for a self-hosted Audiobookshelf server. It speaks the HTTP API over stdio and over stateless Streamable HTTP on 127.0.0.1.
Audiobookshelf is GPL-3.0 software. This connector does not copy that code. It only calls the HTTP API on the server you configure. It is not affiliated with Audiobookshelf. Bring your own API token from your user (Settings → API Keys, or an account token). The connector sends Authorization: Bearer <token>.
The operations table is generated from vendor/ApiRouter.js (copied from Audiobookshelf server/routers/ApiRouter.js). The router has 202 string routes. This connector covers 181 of them in 26 tools. It leaves out 21 endpoints that stream media, download archives, upload files, or open playback sessions. scripts/gen-operations.mjs writes src/operations.ts. Do not edit that file by hand.
Self-hosted servers only. There is no default base URL. ABS_BASE_URL is required. There is no hosted Audiobookshelf cloud to call.
Setup
npm install
npm run ci
npm start
npm run start:httpnpm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication of its own. Keep it on localhost.
{
"mcpServers": {
"audiobookshelf": {
"command": "node",
"args": ["/workspace/connectors/audiobookshelf/dist/index.js"],
"env": {
"ABS_BASE_URL": "http://127.0.0.1:13378",
"ABS_API_TOKEN": "...",
"ABS_ALLOW_WRITES": "false",
"ABS_TOOLSETS": "libraries,items,collections,playlists,me,authors,series,podcasts,search,sessions,stats,tags,genres"
}
}
}
}Docker (HTTP, no authentication — keep it on localhost):
docker build -t audiobookshelf .
docker run -p 127.0.0.1:3000:3000 \
-e ABS_BASE_URL=http://127.0.0.1:13378 \
-e ABS_API_TOKEN=... \
audiobookshelfDo not put tokens in the image.
Regenerate the registry after an ApiRouter bump.
npm run gen:operationsscripts/live-check.mjs talks to a real server over stdio. It needs ABS_BASE_URL and ABS_API_TOKEN, sets ABS_TOOLSETS=all and ABS_ALLOW_WRITES=true, and prints pass or fail lines only. This workspace does not start Audiobookshelf.
Related MCP server: seafile-mcp
Config
Variable | Meaning |
| Required. Self-hosted origin, |
| Bearer token from your Audiobookshelf user. Sent as |
| Must be the literal |
| Comma list of toolsets, or |
| Local request budget. Default 30. Cache hits do not spend it. |
| Upstream timeout. Default 20000. |
| Read cache TTL. Default 60. Writes clear the cache. |
| Contact token in the User-Agent. Must not contain the token. |
|
|
| HTTP port. Default 3000. Bound to |
Invalid values are reported by field name and issue code. The rejected value is not included. The token is redacted in logs, errors, tool results, thrown messages, and URLs.
Safety
GET is a read. POST, PUT, PATCH, and DELETE are writes, except a reviewed list of POST queries in READ_POST_PATHS (batch item get, podcast feed lookup, OPML parse, filesystem path exists, cron validate, authorize). A few GETs that match, check, restore, or test are writes (GET_SIDE_EFFECT_PATHS). Anything not on the read list stays a write.
A write needs confirm: true as a boolean and ABS_ALLOW_WRITES=true. The string "true" is rejected. Otherwise the tool returns a dry-run preview of method, path, query, and redacted body, and it sends nothing. Destructive and credential operations add a warning line on the tool and on the preview. That set covers deletes, scans, match-all, backup restore, user changes, API key create and revoke, password, and settings.
API key create returns the key once, with a shown-only-once note. Later list and get calls redact it. User apiKey, email, token, and password are redacted. Library folder paths stay in successful responses. Error text drops stack traces and filesystem paths.
HTTP 401 is unauthorized. HTTP 403 is forbidden. HTTP 404 is not found. HTTP 400 and 422 are invalid input. HTTP 429 includes Retry-After. Other failures are server, network, or timeout. Response bodies are capped.
Sessions are read and close only. The connector does not start playback, sync open sessions, or bulk-delete session records.
Tools
Default ABS_TOOLSETS publishes 13 tools (123 operations). ABS_TOOLSETS=all publishes 26 tools (181 operations, 74 reads and 107 writes). Each tool takes action plus optional params, query, body, and confirm.
action help with optional target returns the path, query, and body fields for one action. Descriptions list action names only, so the tool list stays small.
Toolset | Tool | Operations | Default |
libraries |
| 26 | yes |
items |
| 18 | yes |
collections |
| 9 | yes |
playlists |
| 10 | yes |
me |
| 23 | yes |
authors |
| 5 | yes |
series |
| 2 | yes |
podcasts |
| 12 | yes |
search |
| 6 | yes |
sessions |
| 4 | yes |
stats |
| 2 | yes |
tags |
| 3 | yes |
genres |
| 3 | yes |
admin |
| 8 | no |
users |
| 9 | no |
backups |
| 5 | no |
filesystem |
| 2 | no |
notifications |
| 8 | no |
emails |
| 5 | no |
cache |
| 2 | no |
tools |
| 4 | no |
feeds |
| 5 | no |
metadata_providers |
| 3 | no |
share |
| 2 | no |
api_keys |
| 4 | no |
tasks |
| 1 | no |
Example. List libraries, then preview a scan.
{ "action": "get" }{ "action": "post_scan", "params": { "id": "lib_..." } }Add "confirm": true only after ABS_ALLOW_WRITES=true.
Exclusions
21 operations are in EXCLUSIONS, each with a reason. The coverage test checks that the router equals the registry plus that list, in both directions.
Audio and ebook file streams, cover and author images, ebook bytes.
Item, library, and backup zip downloads. An MCP text tool cannot carry the archive.
OPML file download.
Multipart uploads (library item, cover, author image, backup). The tool sends JSON and cannot attach a file part.
Playback session start (
/api/items/:id/playand episode play). Sessions are read and close only.Open-session progress sync and local session push.
Bulk session delete. Close is one id only (
POST /api/session/:id/close).Bulk podcast episode media download onto the server.
JSON catalogue, progress, playlist, collection, and admin JSON stay in the registry.
Comparison with michaeldvinci/audiobookshelf-mcp
The Go connector at michaeldvinci/audiobookshelf-mcp exposes these tools (from its README and src):
libraries, library, create_library, item, author, collections, collection, create_collection, add_to_collection, playlists, playlist, create_playlist, add_to_playlist, me, sessions, session, podcasts, podcast, check_podcast_episodes, update_progress, create_backup.
That is a fixed list of 21 tools covering libraries, one item, authors, collections, playlists, me/progress, sessions, podcasts, and backup create. It uses ABS_API_KEY.
This connector covers those areas and more: series, tags, genres, stats, search, users, admin settings, notifications, emails, cache, tools, feeds, metadata providers, share, API keys, tasks, filesystem, logs-adjacent admin JSON, and session close. Writes are dry-run unless confirm: true and ABS_ALLOW_WRITES=true. Responses are parsed with Zod. The token is a Bearer ABS_API_TOKEN and is redacted in every log and error. Admin and users stay off until you opt in.
What this is not
This is not a hosted Audiobookshelf client. There is no default cloud origin. It does not stream audio, download archives, upload files, or start playback. It does not copy Audiobookshelf source. HTTP mode is an unauthenticated localhost transport for your own process.
Live check has not been run yet. See LIVE-CHECK.md.
Regenerating the operations table
src/operations.ts is generated from upstream server/routers/ApiRouter.js (GPL-3.0, not vendored here). To regenerate, download that file from github.com/advplyr/audiobookshelf into vendor/ApiRouter.js and run npm run gen:operations.
License
MIT for this connector. Audiobookshelf itself is GPL-3.0 and is not affiliated with this project.
Available Tools
13 toolsabs_authorsADestructive
abs_authors covers the authors toolset (5 operations). Auth is Authorization Bearer from ABS_API_TOKEN. Self-hosted Audiobookshelf only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and ABS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive or credential actions add an extra warning in the preview: delete, scan, match, purge, backup restore, user changes, API key create or revoke, password, and settings. Actions: delete_by_id, delete_image, get_by_id, patch_by_id, post_match.
Inputs: action (required), body, query, params, +2 more.
abs_collectionsADestructive
abs_collections covers the collections toolset (9 operations). Auth is Authorization Bearer from ABS_API_TOKEN. Self-hosted Audiobookshelf only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and ABS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive or credential actions add an extra warning in the preview: delete, scan, match, purge, backup restore, user changes, API key create or revoke, password, and settings. Actions: delete_book, delete_by_id, get, get_by_id, patch_by_id, post, post_batch_add, post_batch_remove, post_book.
Inputs: action (required), body, query, params, +2 more.
abs_genresADestructive
abs_genres covers the genres toolset (3 operations). Auth is Authorization Bearer from ABS_API_TOKEN. Self-hosted Audiobookshelf only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and ABS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive or credential actions add an extra warning in the preview: delete, scan, match, purge, backup restore, user changes, API key create or revoke, password, and settings. Actions: delete_by_id, get, post_rename.
Inputs: action (required), body, query, params, +2 more.
abs_itemsADestructive
abs_items covers the items toolset (18 operations). Auth is Authorization Bearer from ABS_API_TOKEN. Self-hosted Audiobookshelf only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and ABS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive or credential actions add an extra warning in the preview: delete, scan, match, purge, backup restore, user changes, API key create or revoke, password, and settings. Actions: delete_by_id, delete_cover, delete_file, get_by_id, get_ffprobe, get_metadata_object, patch_cover, patch_ebook_status, patch_media, patch_tracks, post_batch_delete, post_batch_get, post_batch_quickmatch, post_batch_scan, post_batch_update, post_chapters, post_match, post_scan.
Inputs: action (required), body, query, params, +2 more.
abs_librariesADestructive
abs_libraries covers the libraries toolset (26 operations). Auth is Authorization Bearer from ABS_API_TOKEN. Self-hosted Audiobookshelf only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and ABS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive or credential actions add an extra warning in the preview: delete, scan, match, purge, backup restore, user changes, API key create or revoke, password, and settings. Actions: delete_by_id, delete_issues, delete_narrators, get, get_authors, get_by_id, get_collections, get_episode_downloads, get_filterdata, get_items, get_matchall, get_narrators, get_personalized, get_playlists, get_podcast_titles, get_recent_episodes, get_search, get_series, get_series_id_series_id, get_stats, patch_by_id, patch_narrators, post, post_order, post_remove_metadata, post_scan.
Inputs: action (required), body, query, params, +2 more.
abs_meADestructive
abs_me covers the me toolset (23 operations). Auth is Authorization Bearer from ABS_API_TOKEN. Self-hosted Audiobookshelf only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and ABS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive or credential actions add an extra warning in the preview: delete, scan, match, purge, backup restore, user changes, API key create or revoke, password, and settings. Actions: delete_item_bookmark, delete_progress, delete_sessions, get, get_bookmarks, get_bookmarks_library_item_id, get_item_listening_sessions, get_items_in_progress, get_listening_sessions, get_listening_stats, get_progress, get_progress_id_episode_id, get_progress_remove_from_continue_listening, get_series_readd_to_continue_listening, get_series_remove_from_continue_listening, get_sessions, get_stats_year, patch_item_bookmark, patch_password, patch_progress, patch_progress_batch_update, post_ereader_devices, post_item_bookmark.
Inputs: action (required), body, query, params, +2 more.
abs_playlistsADestructive
abs_playlists covers the playlists toolset (10 operations). Auth is Authorization Bearer from ABS_API_TOKEN. Self-hosted Audiobookshelf only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and ABS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive or credential actions add an extra warning in the preview: delete, scan, match, purge, backup restore, user changes, API key create or revoke, password, and settings. Actions: delete_by_id, delete_item, get, get_by_id, patch_by_id, post, post_batch_add, post_batch_remove, post_collection, post_item.
Inputs: action (required), body, query, params, +2 more.
abs_podcastsADestructive
abs_podcasts covers the podcasts toolset (12 operations). Auth is Authorization Bearer from ABS_API_TOKEN. Self-hosted Audiobookshelf only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and ABS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive or credential actions add an extra warning in the preview: delete, scan, match, purge, backup restore, user changes, API key create or revoke, password, and settings. Actions: delete_episode, get_checknew, get_clear_queue, get_downloads, get_episode, get_search_episode, patch_episode, post, post_feed, post_match_episodes, post_opml_create, post_opml_parse.
Inputs: action (required), body, query, params, +2 more.
abs_searchCRead-only
abs_search covers the search toolset (6 operations). Auth is Authorization Bearer from ABS_API_TOKEN. Self-hosted Audiobookshelf only. action help with target returns one action's parameters. Actions: get_authors, get_books, get_chapters, get_covers, get_podcast, get_providers.
Inputs: action (required), body, query, params, +1 more.
abs_seriesA
abs_series covers the series toolset (2 operations). Auth is Authorization Bearer from ABS_API_TOKEN. Self-hosted Audiobookshelf only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and ABS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Actions: get_by_id, patch_by_id.
Inputs: action (required), body, query, params, +2 more.
abs_sessionsA
abs_sessions covers the sessions toolset (4 operations). Auth is Authorization Bearer from ABS_API_TOKEN. Self-hosted Audiobookshelf only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and ABS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Actions: get, get_open, get_session, post_session_close.
Inputs: action (required), body, query, params, +2 more.
abs_statsBRead-only
abs_stats covers the stats toolset (2 operations). Auth is Authorization Bearer from ABS_API_TOKEN. Self-hosted Audiobookshelf only. action help with target returns one action's parameters. Actions: get_server, get_year.
Inputs: action (required), body, query, params, +1 more.
abs_tagsADestructive
abs_tags covers the tags toolset (3 operations). Auth is Authorization Bearer from ABS_API_TOKEN. Self-hosted Audiobookshelf only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and ABS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive or credential actions add an extra warning in the preview: delete, scan, match, purge, backup restore, user changes, API key create or revoke, password, and settings. Actions: delete_by_id, get, post_rename.
Inputs: action (required), body, query, params, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Top-level tools split cleanly by resource, but abs_libraries duplicates capabilities of other tools (get_collections, get_items, get_authors, get_narrators, get_playlists, get_series, get_search, get_stats), so an agent could reasonably pick either abs_collections.get or abs_libraries.get_collections. abs_me also overlaps with abs_sessions (get_listening_sessions vs get_session) and abs_items (bookmarks/progress). The descriptions are templates that never explain when to use the library-scoped variant over the dedicated resource tool.
Every tool follows a uniform abs_<plural-resource> pattern in snake_case, which is highly predictable. Internal action names are also consistently snake_case verb_noun, though some are awkward or generated-looking (get_series_id_series_id, get_progress_id_episode_id, post_batch_get).
13 tools is a good count for an API-covering server and each maps to a recognizable domain object. However, several tools are heavily overloaded (abs_libraries with 26 actions, abs_me with 23, abs_items with 18), so the true surface is much larger than the tool count suggests.
Core media domains are covered (items, libraries, series, authors, collections, playlists, podcasts, search, stats, sessions, me). But the descriptions repeatedly reference destructive actions for users, backups, API keys, and server settings that have no corresponding tool, leaving notable gaps for admin work. There is also no obvious 'help'/'list actions' tool beyond an action=help convention buried in descriptions.
Maintenance
Related MCP Connectors
Manage Podhome podcasts: episodes, chapters, transcripts, clips, people and analytics.
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.
Unofficial, read-only access to your Last.fm listening history, charts, and music lookups.
Search Bluesky posts and feeds; read profiles, threads, and trends. STDIO or Streamable HTTP.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables interaction with a self-hosted Kavita server through its HTTP API, exposing libraries, series, collections, reading lists, search, metadata, statistics, and account/admin operations as MCP tools with read-only defaults and explicit confirmation for writes.12MIT
- AlicenseBqualityBmaintenanceConnects MCP clients to a self-hosted Seafile server through the seahub HTTP API, exposing libraries, files, search, sharing, and optional admin operations over stdio or Streamable HTTP. It defaults to read-focused tools and gates writes behind confirmation, with token redaction and dry-run previews.4MIT
- AlicenseAqualityCmaintenanceEnables MCP clients to interact with a self-hosted comic/library server through its HTTP API, exposing libraries, series, books, collections, readlists, metadata, and administrative operations with read/write safety controls over stdio or Streamable HTTP.7MIT
- AlicenseNot gradedqualityCmaintenanceEnables interaction with self-hosted Miniflux instances through the HTTP API, covering feeds, categories, entries, enclosures, icons, OPML, users, and API keys. Write operations are confirm-gated with dry-run previews and secret redaction.6 npmMIT