abs-mcp

command module
v0.7.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 21, 2026 License: GPL-3.0 Imports: 4 Imported by: 0

README

abs-mcp

GitHub release Go Version License build tests lint coverage

An MCP server that finds what is wrong with an Audiobookshelf library and helps fix it. It is also a command-line tool and a Go client.

Detection is code, correction is judgment. The server runs the checks over the whole library and returns short worklists. You and your client decide what to change.

Install

go install github.com/katbyte/abs-mcp@latest

Needs Audiobookshelf 2.26 or newer.

Quick start

Make an API key in Audiobookshelf under Settings → Users → API Keys. Then register the server with Claude Code:

claude mcp add audiobookshelf -e ABS_SERVER=http://nas:13378 -e ABS_TOKEN=... -e ABS_TOOLSETS=curation -- abs-mcp serve

Ask the client to run audit_all. It shows where the library needs work.

Without ABS_TOOLSETS only five read-only tools load. curation adds the audits and the tools that fix what they find.

The audits

Each audit sweeps the whole library for one kind of mistake. Each name links to its full rules.

audit what it catches
audit_all Every audit in one call, counts only. Start here.
audit_unmatched Books never matched to a store record. Fix with item_match.
audit_matched Books matched to a recording other than the one on disk. Fix with item_match.
audit_missing An empty field: cover, description, narrator, series and more. Fix with item_edit.
audit_issues Records whose folder is gone or holds nothing playable. Fix with library_issues_merge or library_issues_remove.
audit_no_audio Books with no audio at all, usually an ebook in an audiobook library.
audit_unplayable Audio that will not play: locked to a store's player, unreadable or cut short.
audit_path A folder name that disagrees with the title, author, year or series. Fix with item_edit.
audit_chapters Chapters out of order, past the end of the audio, or one chapter over a long book. Fix with item_chapters_set.
audit_duplicates The same book held more than once, and incomplete copies. Confirm with item_compare_audio.
audit_abridged Books that are probably abridged but not marked so. Fix with item_edit.
audit_series Gaps, one series spelled two ways, wrong numbers and bad names. Fix with series_merge or series_edit.
audit_authors Authors that are unmatched, empty, duplicated or wrongly matched. Fix with author_match or author_edit.
audit_narrators Author and narrator swapped, and misspelt narrator names. Fix with item_edit or metadata_rename.
audit_genres Genres and tags that are placeholders, repeats or too rarely used. Fix with metadata_rename.
audit_spelling One value spelled several ways in genres, tags, languages and publishers. Fix with metadata_rename.
audit_whitespace Stray spaces in titles, names, folders and files. Fix with item_edit, author_edit or series_edit.
audit_covers Covers that are missing, small, not square or carry a store ribbon. Fix with item_cover_edit or item_cover_upgrade.
audit_unembedded Audio files whose tags do not carry the library's metadata. Fix with item_embed_metadata.
audit_podcasts Podcasts with nothing downloaded or a feed gone quiet. Fix with podcast_episode_download or podcast_check_new.

What else is here

  • 100 tools cover the whole Audiobookshelf API, so what an audit finds can be fixed in the same session.
  • A Go client, sdk/abs, works on its own. It covers all 202 API routes.
  • An OpenAPI document of the whole Audiobookshelf REST API, in api-defs/. Audiobookshelf publishes no current one, so this is read from the server's own source: every route but sign-in and audio streaming, 218 in all. pandorest generates the Go client in sdk/abs from it. See how it is made.
  • Proven on a real library. A large collection, gathered over years, was cleaned up with these tools. Most of the audits exist because that library had the problem.

What keeps a library safe

  • --read-only loads only the tools that change nothing.
  • The tools that delete load only with --enable-delete.
  • A tool that erases files, removes many records, or writes a store's details over a book's first says what it would do. It changes nothing until called again with confirm.

More

How this is built

The code is written with Claude Code. I review it, then prune or rework it until it has the shape I want. I set the design, the scope and the audit rules, and I decide what stays.

Every tool and every client method must have a live test against a real Audiobookshelf in Docker. CI fails otherwise.

CI also runs:

  • Lint: golangci-lint, actionlint, yamllint, shellcheck, markdownlint and a spelling check.
  • Security: CodeQL, govulncheck, a vulnerability scan of the built binary, and an audit of the workflows.
  • Dependencies: a check that go.mod and the vendored code agree.

Documentation

Overview

Package main implements abs-mcp, an MCP server and CLI for curating an Audiobookshelf library.

Directories

Path Synopsis
Package cli implements the abs-mcp command line interface: the cobra commands, flag and config handling, and the MCP server exposing Audiobookshelf library tools to AI clients.
Package cli implements the abs-mcp command line interface: the cobra commands, flag and config handling, and the MCP server exposing Audiobookshelf library tools to AI clients.
lib
audioprobe
Package audioprobe reads what an audio file's container says about it, a few kilobytes at a time: which container it really is, whatever its extension says, and whether its audio is locked to a store's player.
Package audioprobe reads what an audio file's container says about it, a few kilobytes at a time: which container it really is, whatever its extension says, and whether its audio is locked to a store's player.
audiosample
Package audiosample reads stretches of a book's audio from an Audiobookshelf server: seconds or minutes from anywhere in the book, as mono PCM at the rate asked for, across its files in play order.
Package audiosample reads stretches of a book's audio from an Audiobookshelf server: seconds or minutes from anywhere in the book, as mono PCM at the rate asked for, across its files in play order.
audiosample/calibration command
Command calibration fetches the recordings item_compare_audio is calibrated on into a cache outside the repository, with the manifest the calibration test reads.
Command calibration fetches the recordings item_compare_audio is calibrated on into a cache outside the repository, with the manifest the calibration test reads.
sdk
abs
Package abs is a typed client for Audiobookshelf API 2.37.1, generated by pandorest from the definitions in api-defs/audiobookshelf-2.37.1, which were imported from api-defs/audiobookshelf-openapi-2.37.1.json.
Package abs is a typed client for Audiobookshelf API 2.37.1, generated by pandorest from the definitions in api-defs/audiobookshelf-2.37.1, which were imported from api-defs/audiobookshelf-openapi-2.37.1.json.
apicheck command
Command apicheck reports how much of the Audiobookshelf API the API document covers, and fails when a route is missing.
Command apicheck reports how much of the Audiobookshelf API the API document covers, and fails when a route is missing.
pandorest command
Command pandorest generates sdk/abs with github.com/katbyte/pandorest from the Audiobookshelf API document under api-defs, which spec writes by reading the server's own source, because Audiobookshelf publishes no complete one.
Command pandorest generates sdk/abs with github.com/katbyte/pandorest from the Audiobookshelf API document under api-defs, which spec writes by reading the server's own source, because Audiobookshelf publishes no complete one.
pandorest/answers
Package answers keeps what a real Audiobookshelf server answers, one file for each operation of the API document, so the document's types can be checked against, and filled from, what the server says rather than what its source suggests.
Package answers keeps what a real Audiobookshelf server answers, one file for each operation of the API document, so the document's types can be checked against, and filled from, what the server says rather than what its source suggests.
Package tools defines the MCP tools exposed by abs-mcp, split by the resource they act on (server.go, libraries.go, items.go, ...).
Package tools defines the MCP tools exposed by abs-mcp, split by the resource they act on (server.go, libraries.go, items.go, ...).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL