![\"Audiobookshelf](\"docs/assets/abs-mcp-logo.svg\"){kind=logo}
\n\n \n
\n A Go MCP server for inspecting and safely operating Audiobookshelf libraries.\n
\n\n`abs-mcp` exposes safe, typed MCP tools and resources for agents that need to\ninspect Audiobookshelf libraries, diagnose scans, and optionally trigger bounded\nmaintenance workflows.\n\n## Table of Contents\n\n- [Highlights](#highlights)\n- [Audiobook Organizer Compatibility](#audiobook-organizer-compatibility)\n- [AI Generated Comparison - Last updated 2026-06-22](#ai-generated-comparison---last-updated-2026-06-22)\n- [Quick Start](#quick-start)\n- [MCP Surface](#mcp-surface)\n- [Configuration](#configuration)\n- [Safety](#safety)\n- [Installation](#installation)\n - [Client Configs](#client-configs)\n- [Local Development](#local-development)\n- [Tests](#tests)\n- [CI and Releases](#ci-and-releases)\n- [MCP Registry](#mcp-registry)\n\n## Highlights\n\n- Read-only by default; scan and cleanup tools require `ABS_READ_ONLY=false`.\n- Ships as a local stdio MCP server from a single Go binary or Docker image,\n with optional Streamable HTTP mode for hosted or multi-client deployments.\n- Supports env vars, Docker-style env files, extra headers, and custom TLS CA\n bundles.\n- Includes source-backed Audiobookshelf API inventory resources and repeatable\n fixture tests.\n- Publishes release binaries and a GHCR image suitable for official MCP\n Registry metadata.\n\n## Audiobook Organizer Compatibility\n\nI built this MCP server to work especially well alongside\n[jeeftor/audiobook-organizer](https://github.com/jeeftor/audiobook-organizer).\nWhile it exposes the normal Audiobookshelf MCP tools for inspecting libraries,\nitems, metadata, and server state, one of its most useful workflows is auditing\nwhether books are actually organized the way you expect on disk.\n\nThe `abs_find_misorganized_items` tool checks Audiobookshelf item paths against\nsupported folder layout conventions, including author/title and\nauthor/series/title structures. It is audit-only, so it reports likely\nmisconfigured or misplaced books without moving or deleting files. That makes it\na good companion to Audiobook Organizer: use this MCP server to identify layout\nproblems from Audiobookshelf's perspective, then use Audiobook Organizer to\nclean up or standardize the underlying files.\n\n\n## AI Generated Comparison - Last updated 2026-06-22\n\nThis comparison is generated from public GitHub repository metadata, public\nproject READMEs, registry/package searches, and this repository's current docs.\nIt is descriptive rather than a recommendation.\n\nMutating versus non-mutating coverage:\n\n- `jeeftor/abs-mcp` exposes read-only inspection, search, author, series,\n collection, current-user progress/bookmark/listening reads, backups, ereader\n device discovery, ebook send preview, metadata-object, layout-audit,\n resources, and prompts by default. Ebook device-send tools perform outbound\n delivery but do not mutate Audiobookshelf library, metadata, backup,\n progress, collection, or playlist state, so they remain usable in read-only\n mode. Scan, cleanup, cover, chapter, progress/bookmark writes, backup\n creation, metadata, and collection/playlist create/update/add/delete/remove\n tools can mutate Audiobookshelf state only when `ABS_READ_ONLY=false`;\n destructive operations also require exact confirmation strings.\n- `michaeldvinci/audiobookshelf-mcp` exposes a broad management surface with\n read tools plus mutating operations such as library, collection, playlist,\n progress, and backup actions. No public README evidence was found for a\n global default read-only gate during this pass.\n- `sandymac/audiobookshelf-mcp` is mostly read/query oriented, with optional\n progress and bookmark mutation tools that are disabled by default.\n- `sierikov/audiobookshelf-mcp` presents a read-only browsing, search, progress,\n stats, author, series, and collection surface.\n- `ForceConstant/audiobookshelf_mcp` appears to be generated from\n Audiobookshelf OpenAPI material; mutating coverage and safety gates were not\n determinable from the public README.\n\nSources checked in this pass:\n\n- Public GitHub repositories:\n [`michaeldvinci/audiobookshelf-mcp`](https://github.com/michaeldvinci/audiobookshelf-mcp),\n [`sandymac/audiobookshelf-mcp`](https://github.com/sandymac/audiobookshelf-mcp),\n [`sierikov/audiobookshelf-mcp`](https://github.com/sierikov/audiobookshelf-mcp),\n [`ForceConstant/audiobookshelf_mcp`](https://github.com/ForceConstant/audiobookshelf_mcp),\n and [`schmidt-software/mcp-audiobookshelf`](https://github.com/schmidt-software/mcp-audiobookshelf).\n- Search checks for additional npm and PyPI packages did not surface a\n credible Audiobookshelf-specific MCP server beyond the GitHub targets above.\n\n| Server | Shape | Confirmed strengths | Safety posture | Difference from `jeeftor/abs-mcp` |\n| --- | --- | --- | --- | --- |\n| [`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. |\n| [`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. |\n| [`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. |\n| [`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. |\n\nWeak or placeholder hits, such as\n[`schmidt-software/mcp-audiobookshelf`](https://github.com/schmidt-software/mcp-audiobookshelf),\nwere excluded when no implementation or feature evidence was available.\n\n### Candidate gaps from this comparison\n\n- Candidate: evaluate a bounded podcast workflow. Public peers expose podcast\n browsing or episode checks; this server currently has no dedicated podcast\n tools beyond generic item/library APIs.\n- Candidate: evaluate library creation/update workflows. One public peer exposes\n library creation, but this remains an admin-level operation that would need\n source verification, fixture coverage, `ABS_READ_ONLY=false`, and destructive\n confirmations for any delete/remove path.\n- Candidate: evaluate `.mcpb` desktop bundle packaging. One public peer ships\n Claude Desktop `.mcpb` bundles; this server currently publishes binaries,\n Docker/GHCR artifacts, and MCP Registry metadata instead.\n- Existing candidate still relevant:\n [#5](https://github.com/jeeftor/abs-mcp/issues/5) tracks Streamable HTTP\n transport support. Public peers show both HTTP/SSE and Streamable HTTP shapes,\n so the issue should be reconciled with the current optional Streamable HTTP\n implementation and any remaining hardening or documentation gaps.\n\n\n## Quick Start\n\nRun a downloaded release binary over MCP stdio:\n\n```bash\nABS_BASE_URL=http://localhost:13378 \\\nABS_API_KEY=... \\\nABS_READ_ONLY=true \\\n/path/to/abs-mcp\n```\n\nOr run the container image:\n\n```bash\ndocker run --rm -i \\\n -e ABS_BASE_URL=http://host.docker.internal:13378 \\\n -e ABS_API_KEY=... \\\n -e ABS_READ_ONLY=true \\\n ghcr.io/jeeftor/abs-mcp:0.5.0\n```\n\nFor client-specific snippets, see [Client Configs](#client-configs).\n\n## MCP Surface\n\n### Tools\n\nThe server exposes all registered tools in the README, grouped by whether they\ncan change Audiobookshelf state.\n\nRead-only and non-ABS-mutating tools:\n\n- `abs_health_check`\n- `abs_list_libraries`\n- `abs_get_library`\n- `abs_list_library_items`\n- `abs_get_library_item`\n- `abs_search_library`\n- `abs_search_ebooks`\n- `abs_preview_ebook_device_send`\n- `abs_get_library_stats`\n- `abs_get_filter_data`\n- `abs_list_library_authors`\n- `abs_get_author`\n- `abs_list_library_series`\n- `abs_get_series`\n- `abs_list_collections`\n- `abs_get_collection`\n- `abs_get_items_in_progress`\n- `abs_get_listening_stats`\n- `abs_list_listening_sessions`\n- `abs_get_item_progress`\n- `abs_list_bookmarks`\n- `abs_list_backups`\n- `abs_list_ereader_devices`\n- `abs_send_ebook_to_device`\n- `abs_send_ebook_by_query`\n- `abs_get_item_metadata_object`\n- `abs_find_misorganized_items`\n\nImplemented mutating tools:\n\n- `abs_scan_library`\n- `abs_scan_library_and_wait`\n- `abs_scan_item`\n- `abs_update_item_metadata`\n- `abs_update_item_progress`\n- `abs_create_bookmark`\n- `abs_update_bookmark`\n- `abs_create_backup`\n- `abs_update_item_cover`\n- `abs_remove_item_cover`\n- `abs_update_item_chapters`\n- `abs_create_collection`\n- `abs_update_collection`\n- `abs_delete_collection`\n- `abs_add_collection_item`\n- `abs_remove_collection_item`\n- `abs_create_playlist`\n- `abs_update_playlist`\n- `abs_delete_playlist`\n- `abs_add_playlist_item`\n- `abs_remove_playlist_item`\n- `abs_remove_library_items_with_issues`\n\nPlanned mutating tools advertised for discovery:\n\n- `abs_match_item`\n- `abs_update_item_tracks`\n\nTools that mutate Audiobookshelf state are blocked by default because\n`ABS_READ_ONLY` defaults to `true`. Scan tools, issue cleanup, cover updates,\nchapter updates, typed item metadata, current-user progress/bookmark writes,\nbackup creation, and collection/playlist create, update, add-item, delete, and\nremove-item tools are implemented mutating operations. Ebook send-to-device\ndelivery and guarded query-based device send only email an already-existing\nebook file out; they create, change, or delete nothing on Audiobookshelf\n(library, metadata, backup, progress, collection, or playlist state), so they\nare allowed while read-only mode is enabled. Read-only here means \"does not\nmutate Audiobookshelf state,\" not \"produces no outbound side effect\"; if you\nneed to suppress device delivery entirely, do not configure an ereader device.\nUse `abs_preview_ebook_device_send` first for device-send UX: it is\nread-only, returns compact ebook candidates, sanitized device names, `ready`,\nthe exact confirmation string when one ebook and one saved device name resolve,\nand `nextTool` for the send step. ABS still authorizes device access and\ndelivery during the final device-send call.\nRemaining planned mutating tools, including item matching and item track\nupdates, are advertised for discovery but return a not-implemented error after\nread-only checks until their ABS source and fixture behavior is verified.\n\n### Resources\n\n- `abs://server/info`\n- `abs://libraries`\n- `abs://libraries/{library_id}`\n- `abs://libraries/{library_id}/items?limit=...&offset=...`\n- `abs://libraries/{library_id}/stats`\n- `abs://libraries/{library_id}/filterdata`\n- `abs://items/{item_id}`\n- `abs://items/{item_id}/metadata-object`\n- `abs://api-inventory/current`\n- `abs://fixture/status`\n\n### Prompts\n\n- `abs_library_audit`\n- `abs_scan_troubleshooting`\n- `abs_api_update_review`\n\nSee [docs/tools.md](docs/tools.md) for tool inputs, output shapes, mutation\nbehavior, and common errors.\n\n## Configuration\n\nEnvironment variables and env files are the preferred configuration paths for\nMCP clients, containers, and other launchers that inject secrets:\n\n```bash\nexport ABS_BASE_URL=http://localhost:13388\nexport ABS_API_KEY=...\nexport ABS_READ_ONLY=true\nexport ABS_TIMEOUT=30s\nexport ABS_FIXTURE_DIR=test/abs\nexport ABS_EXTRA_HEADERS_FILE=/path/to/headers.json\nexport ABS_TLS_CA_CERT_FILE=/path/to/corporate-ca.pem\nexport ABS_TLS_INSECURE_SKIP_VERIFY=false\nexport ABS_TRANSPORT=stdio\nexport ABS_HTTP_ADDR=127.0.0.1:3333\nexport ABS_HTTP_PATH=/mcp\nexport ABS_HTTP_BEARER_TOKEN=\n```\n\nThe server can load those same values from a Docker-style env file:\n\n```bash\ngo run ./cmd/abs-mcp --env-file /path/to/.env\n```\n\nThe server also accepts matching Cobra/Viper CLI flags. Precedence is explicit\nCLI flags, then process environment variables, then `--env-file`, then built-in\ndefaults:\n\n```bash\ngo run ./cmd/abs-mcp \\\n --env-file /path/to/.env \\\n --base-url http://localhost:13388 \\\n --api-key ... \\\n --read-only=true \\\n --timeout 30s \\\n --fixture-dir test/abs \\\n --extra-headers-file /path/to/headers.json \\\n --header 'CF-Access-Client-Id=...' \\\n --header 'CF-Access-Client-Secret=...' \\\n --tls-ca-cert-file /path/to/corporate-ca.pem \\\n --transport stdio \\\n --http-bearer-token ...\n```\n\nPrefer `ABS_API_KEY` and `ABS_HTTP_BEARER_TOKEN` over `--api-key` and\n`--http-bearer-token` outside short local debugging sessions so tokens do not\nland in shell history or process listings.\n\n| Environment variable | CLI flag | Default |\n| --- | --- | --- |\n| n/a | `--env-file` | unset |\n| `ABS_BASE_URL` | `--base-url` | required |\n| `ABS_API_KEY` | `--api-key` | required |\n| `ABS_READ_ONLY` | `--read-only` | `true` |\n| `ABS_TIMEOUT` | `--timeout` | `30s` |\n| `ABS_FIXTURE_DIR` | `--fixture-dir` | `test/abs` |\n| `ABS_EXTRA_HEADERS_FILE` | `--extra-headers-file` | unset |\n| n/a | `--header NAME=VALUE` | unset |\n| `ABS_TLS_CA_CERT_FILE` | `--tls-ca-cert-file` | unset |\n| `ABS_TLS_INSECURE_SKIP_VERIFY` | `--tls-insecure-skip-verify` | `false` |\n| `ABS_TRANSPORT` | `--transport` | `stdio` |\n| `ABS_HTTP_ADDR` | `--http-addr` | `127.0.0.1:3333` |\n| `ABS_HTTP_PATH` | `--http-path` | `/mcp` |\n| `ABS_HTTP_BEARER_TOKEN` | `--http-bearer-token` | unset |\n\nUse `ABS_TRANSPORT=http` or `--transport=http` to serve stateless Streamable\nHTTP at `http://