abs-mcp

<p align="center">
  <img src="docs/assets/abs-mcp-logo.svg" width="112" alt="Audiobookshelf MCP logo">
</p>

<h1 align="center">Audiobookshelf MCP Server</h1>

<p align="center">
  A Go MCP server for inspecting and safely operating Audiobookshelf libraries.
</p>

`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](#highlights)
- [Audiobook Organizer Compatibility](#audiobook-organizer-compatibility)
- [AI Generated Comparison - Last updated 2026-06-03](#ai-generated-comparison---last-updated-2026-06-03)
- [Quick Start](#quick-start)
- [MCP Surface](#mcp-surface)
- [Configuration](#configuration)
- [Safety](#safety)
- [Installation](#installation)
  - [Client Configs](#client-configs)
- [Local Development](#local-development)
- [Tests](#tests)
- [CI and Releases](#ci-and-releases)
- [MCP Registry](#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](https://github.com/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:START -->
## AI Generated Comparison - Last updated 2026-06-03

This comparison is generated from public project READMEs, registry pages, 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 reads, metadata-object,
  layout-audit, resources, and prompts by default. Scan, cleanup, cover,
  chapter, and non-destructive collection/playlist create/update/add 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.

Candidate gaps from this comparison:

- Candidate: add current-user listening stats and recent-session read tools.
  Other servers expose progress-adjacent stats/session inspection; this server
  now exposes current-user progress and bookmark reads plus non-destructive
  progress/bookmark mutations, but not recent sessions or listening statistics.
- [#4](https://github.com/jeeftor/abs-mcp/issues/4): Investigate safely gated
  backup and server-admin MCP tools. At least one public peer exposes backup
  creation, but any admin operation here should be source-verified,
  fixture-tested, and gated.

| Server | Shape | Confirmed strengths | Safety posture | Difference from `jeeftor/abs-mcp` |
| --- | --- | --- | --- | --- |
| [`michaeldvinci/audiobookshelf-mcp`](https://github.com/michaeldvinci/audiobookshelf-mcp) | Go stdio server with release binaries. | Broad general Audiobookshelf management, including libraries, items, authors, collections, playlists, user info, sessions, podcasts, progress updates, and backups. | Exposes mutating tools; no global default read-only gate was found in the public README during this comparison pass. | Broader generic management surface, but less conservative. This server now overlaps typed metadata and collection/playlist create and add-item coverage, while adding default read-only gating, destructive confirmations, a misorganized-file audit, source-backed API inventory, MCP resources/prompts, and guarded cover/chapter repair tooling. |
| [`sandymac/audiobookshelf-mcp`](https://github.com/sandymac/audiobookshelf-mcp) | Rust server with stdio plus HTTP/SSE support. | Read/query surface for libraries, search, progress, stats, recent sessions, and optional progress/bookmark mutations. | Mutating tools are disabled by default and must be explicitly enabled. HTTP mode recommends bearer auth and TLS proxying. | Similar safety model. It has stats/session tools; this server now overlaps progress/bookmark mutation coverage while adding optional Streamable HTTP, source-backed API inventory, resources/prompts, organizer-oriented audits, fixture workflows, and guarded metadata/repair/catalog mutation tools. |
| [`sierikov/audiobookshelf-mcp`](https://github.com/sierikov/audiobookshelf-mcp) | Go server with read-oriented tooling and release binaries. | Read-only browsing and search across libraries, items, progress, stats, sessions, series, authors, and collections. | Public README presents it as read-only. | Overlaps this server's read-only browsing surface, including progress, author, series, and collection reads, but no public evidence was found for controlled repair/catalog mutation workflows, source-backed API inventory, MCP prompts/resources, or organizer-focused audit tooling. |
| [`ForceConstant/audiobookshelf_mcp`](https://github.com/ForceConstant/audiobookshelf_mcp) | Generated OpenAPI MCP bridge with streamable HTTP and Docker-oriented files. | Broad generated API exposure from Audiobookshelf OpenAPI material. | Not determinable from the public README; generated API exposure may include mutating endpoints, but the README does not enumerate safety controls. | Less curated and less operator-specific. This project intentionally exposes bounded, typed tools with read-only gating and fixture-backed behavior checks instead of exposing every route directly. |

Weak or placeholder hits, such as
[`schmidt-software/mcp-audiobookshelf`](https://github.com/schmidt-software/mcp-audiobookshelf),
were excluded when no implementation or feature evidence was available.
<!-- AI-GENERATED-COMPARISON:END -->

## Quick Start

Run a downloaded release binary over MCP stdio:

```bash
ABS_BASE_URL=http://localhost:13378 \
ABS_API_KEY=... \
ABS_READ_ONLY=true \
/path/to/abs-mcp
```

Or run the container image:

```bash
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.3.0
```

For client-specific snippets, see [Client Configs](#client-configs).

## MCP Surface

### Tools

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

Read-only tools:

- `abs_health_check`
- `abs_list_libraries`
- `abs_get_library`
- `abs_list_library_items`
- `abs_get_library_item`
- `abs_search_library`
- `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_item_progress`
- `abs_list_bookmarks`
- `abs_list_backups`
- `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_add_collection_item`
- `abs_create_playlist`
- `abs_update_playlist`
- `abs_add_playlist_item`
- `abs_remove_library_items_with_issues`

Planned mutating tools advertised for discovery:

- `abs_match_item`
- `abs_update_item_tracks`
- `abs_delete_collection`
- `abs_remove_collection_item`
- `abs_delete_playlist`
- `abs_remove_playlist_item`

Mutating tools are blocked by default because `ABS_READ_ONLY` defaults to
`true`. Scan tools, issue cleanup, `abs_update_item_cover`,
`abs_remove_item_cover`, `abs_update_item_chapters`, typed item metadata,
current-user progress/bookmark writes, and non-destructive collection/playlist
create, update, and add-item tools are implemented. Remaining planned mutating
tools, including item matching,
delete/remove collection and playlist operations, and item track updates, are
advertised for discovery but return a not-implemented error after read-only and
confirmation checks until their ABS source and fixture behavior is verified.

### Resources

- `abs://server/info`
- `abs://libraries`
- `abs://libraries/{library_id}`
- `abs://libr