Audiobookshelf MCP

Audiobookshelf MCP Server

A Go MCP server for inspecting and safely operating Audiobookshelf libraries.

abs-mcp exposes safe, typed MCP tools and resources for agents that need to inspect Audiobookshelf libraries, diagnose scans, and optionally trigger bounded maintenance workflows.

Table of Contents

• Highlights
• Audiobook Organizer Compatibility
• AI Generated Comparison - Last updated 2026-06-22
• Quick Start
• MCP Surface
• Configuration
• Safety
• Installation
• Client Configs
• Local Development
• Tests
• CI and Releases
• MCP Registry

Highlights

• Read-only by default; scan and cleanup tools require ABS_READ_ONLY=false.
• Ships as a local stdio MCP server from a single Go binary or Docker image, with optional Streamable HTTP mode for hosted or multi-client deployments.
• Supports env vars, Docker-style env files, extra headers, and custom TLS CA bundles.
• Includes source-backed Audiobookshelf API inventory resources and repeatable fixture tests.
• Publishes release binaries and a GHCR image suitable for official MCP Registry metadata.

Audiobook Organizer Compatibility

I built this MCP server to work especially well alongside jeeftor/audiobook-organizer. While it exposes the normal Audiobookshelf MCP tools for inspecting libraries, items, metadata, and server state, one of its most useful workflows is auditing whether books are actually organized the way you expect on disk.

The abs_find_misorganized_items tool checks Audiobookshelf item paths against supported folder layout conventions, including author/title and author/series/title structures. It is audit-only, so it reports likely misconfigured or misplaced books without moving or deleting files. That makes it a good companion to Audiobook Organizer: use this MCP server to identify layout problems from Audiobookshelf's perspective, then use Audiobook Organizer to clean up or standardize the underlying files.

AI Generated Comparison - Last updated 2026-06-22

This comparison is generated from public GitHub repository metadata, public project READMEs, registry/package searches, and this repository's current docs. It is descriptive rather than a recommendation.

Mutating versus non-mutating coverage:

• jeeftor/abs-mcp exposes read-only inspection, search, author, series, collection, current-user progress/bookmark/listening reads, backups, ereader device discovery, ebook send preview, metadata-object, layout-audit, resources, and prompts by default. Ebook device-send tools perform outbound delivery but do not mutate Audiobookshelf library, metadata, backup, progress, collection, or playlist state, so they remain usable in read-only mode. Scan, cleanup, cover, chapter, progress/bookmark writes, backup creation, metadata, and collection/playlist create/update/add/delete/remove tools can mutate Audiobookshelf state only when ABS_READ_ONLY=false; destructive operations also require exact confirmation strings.
• michaeldvinci/audiobookshelf-mcp exposes a broad management surface with read tools plus mutating operations such as library, collection, playlist, progress, and backup actions. No public README evidence was found for a global default read-only gate during this pass.
• sandymac/audiobookshelf-mcp is mostly read/query oriented, with optional progress and bookmark mutation tools that are disabled by default.
• sierikov/audiobookshelf-mcp presents a read-only browsing, search, progress, stats, author, series, and collection surface.
• ForceConstant/audiobookshelf_mcp appears to be generated from Audiobookshelf OpenAPI material; mutating coverage and safety gates were not determinable from the public README.

Sources checked in this pass:

• Public GitHub repositories: michaeldvinci/audiobookshelf-mcp, sandymac/audiobookshelf-mcp, sierikov/audiobookshelf-mcp, ForceConstant/audiobookshelf_mcp, and schmidt-software/mcp-audiobookshelf.
• Search checks for additional npm and PyPI packages did not surface a credible Audiobookshelf-specific MCP server beyond the GitHub targets above.

Weak or placeholder hits, such as schmidt-software/mcp-audiobookshelf, were excluded when no implementation or feature evidence was available.

Candidate gaps from this comparison

• Candidate: evaluate a bounded podcast workflow. Public peers expose podcast browsing or episode checks; this server currently has no dedicated podcast tools beyond generic item/library APIs.
• Candidate: evaluate library creation/update workflows. One public peer exposes library creation, but this remains an admin-level operation that would need source verification, fixture coverage, ABS_READ_ONLY=false, and destructive confirmations for any delete/remove path.
• Candidate: evaluate .mcpb desktop bundle packaging. One public peer ships Claude Desktop .mcpb bundles; this server currently publishes binaries, Docker/GHCR artifacts, and MCP Registry metadata instead.
• Existing candidate still relevant: #5 tracks Streamable HTTP transport support. Public peers show both HTTP/SSE and Streamable HTTP shapes, so the issue should be reconciled with the current optional Streamable HTTP implementation and any remaining hardening or documentation gaps.

Quick Start

Run a downloaded release binary over MCP stdio:

ABS_BASE_URL=http://localhost:13378 \

ABS_API_KEY=... \ ABS_READ_ONLY=true \ /path/to/abs-mcp

Or run the container image:

docker run --rm -i \

-e ABS_BASE_URL=http://host.docker.internal:13378 \ -e ABS_API_KEY=... \ -e ABS_READ_ONLY=true \ ghcr.io/jeeftor/abs-mcp:0.5.0

For client-specific snippets, see Client Configs.

MCP Surface

Tools

The server exposes all registered tools in the README, grouped by whether they can change Audiobookshelf state.

Read-only and non-ABS-mutating tools:

• abs_health_check
• abs_list_libraries
• abs_get_library
• abs_list_library_items
• abs_get_library_item
• abs_search_library
• abs_search_ebooks
• abs_preview_ebook_device_send
• abs_get_library_stats
• abs_get_filter_data
• abs_list_library_authors
• abs_get_author
• abs_list_library_series
• abs_get_series
• abs_list_collections
• abs_get_collection
• abs_get_items_in_progress
• abs_get_listening_stats
• abs_list_listening_sessions
• abs_get_item_progress
• abs_list_bookmarks
• abs_list_backups
• abs_list_ereader_devices
• abs_send_ebook_to_device
• abs_send_ebook_by_query
• abs_get_item_metadata_object
• abs_find_misorganized_items

Implemented mutating tools:

• abs_scan_library
• abs_scan_library_and_wait
• abs_scan_item
• abs_update_item_metadata
• abs_update_item_progress
• abs_create_bookmark
• abs_update_bookmark
• abs_create_backup
• abs_update_item_cover
• abs_remove_item_cover
• abs_update_item_chapters
• abs_create_collection
• abs_update_collection
• abs_delete_collection
• abs_add_collection_item
• abs_remove_collection_item
• abs_create_playlist
• abs_update_playlist
• abs_delete_playlist
• abs_add_playlist_item
• abs_remove_playlist_item
• abs_remove_library_items_with_issues

Planned mutating tools advertised for discovery:

• abs_match_item
• abs_update_item_tracks

Tools that mutate Audiobookshelf state are blocked by default because ABS_READ_ONLY defaults to true. Scan tools, issue cleanup, cover updates, chapter updates, typed item metadata, current-user progress/bookmark writes, backup creation, and collection/playlist create, update, add-item, delete, and remove-item tools are implemented mutating operations. Ebook send-to-device delivery and guarded query-based device send only email an already-existing ebook file out; they create, change, or delete nothing on Audiobookshelf (library, metadata, backup, progress, collection, or playlist state), so they are allowed while read-only mode is enabled. Read-only here means "does not mutate Audiobookshelf state," not "produces no outbound side effect"; if you need to suppress device delivery entirely, do not configure an ereader device. Use `abs_preview_ebook_device_s