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-22](#ai-generated-comparison---last-updated-2026-06-22)
- [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-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`](https://github.com/michaeldvinci/audiobookshelf-mcp),
  [`sandymac/audiobookshelf-mcp`](https://github.com/sandymac/audiobookshelf-mcp),
  [`sierikov/audiobookshelf-mcp`](https://github.com/sierikov/audiobookshelf-mcp),
  [`ForceConstant/audiobookshelf_mcp`](https://github.com/ForceConstant/audiobookshelf_mcp),
  and [`schmidt-software/mcp-audiobookshelf`](https://github.com/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.

| 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; GitHub metadata showed latest release `0.0.5` on 2025-11-11. | 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 overlaps more typed repair/catalog workflows now while adding default read-only gating, destructive confirmations, source-backed API inventory, MCP resources/prompts, organizer-oriented audit tooling, and fixture-backed behavior checks. |
| [`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 keeps the mutating surface narrow; this server adds source-backed API inventory, resources/prompts, organizer-oriented audits, fixture workflows, typed metadata/cover/chapter/catalog tools, and explicit destructive confirmations. |
| [`sierikov/audiobookshelf-mcp`](https://github.com/sierikov/audiobookshelf-mcp) | Go server with read-oriented tooling, release binaries, `.mcpb` Claude Desktop bundles, and an MCP Registry entry. | Read-only browsing and search across libraries, items, progress, stats, sessions, series, authors, and collections. | Public README presents all tools as read-only with no writes, playback control, or user management. | 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, organizer-focused audit tooling, or Docker fixture workflows. |
| [`ForceConstant/audiobookshelf_mcp`](https://github.com/ForceConstant/audiobookshelf_mcp) | Generated OpenAPI MCP bridge with Streamable HTTP on port 3000 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.

### 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](https://github.com/jeeftor/abs-mcp/issues/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.
<!-- 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.5.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 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