Audiobookshelf MCP server
Commit Sep 16, 2026Allows an AI client to inspect, search, and manage Audiobookshelf libraries, including metadata, progress, and maintenance workflows.
Also known as jeeftor/abs-mcp, abs-mcp
- Stars
- 1
- Tools
- 51
- Downloads, 30 days
- —
- Latest version
- 0.6.0
- Last commit
- Sep 16, 2026
- License
- MIT
What is Audiobookshelf MCP?
Audiobookshelf allows an AI client to inspect, search, and manage Audiobookshelf libraries, including metadata, progress, and maintenance workflows. It exposes 51 tools, such as abs_health_check, abs_list_libraries, abs_get_library.
Summary generated from the project's README
About Audiobookshelf MCP server
Audiobookshelf MCP provides a specialized interface for AI agents to interact with Audiobookshelf libraries. It allows for deep inspection of metadata, search capabilities, and management of listening progress, bookmarks, and collections. The server is designed with a safety-first approach, operating in a read-only mode by default to prevent accidental changes to your library. To enable mutating actions like scanning libraries, updating metadata, or managing playlists, you must explicitly set the ABS_READ_ONLY environment variable to false.
Developers can deploy this server as a local stdio process using a single Go binary or via a Docker container. It also supports an optional Streamable HTTP mode for hosted environments. The server is particularly useful for auditing file structures, as it includes specific tools to identify misorganized items. Users will need to provide their Audiobookshelf base URL and an API key during configuration to establish a connection.
What you can do with it
- 1Audit library file organizationAn AI can check if your audiobook files follow your preferred folder structures like author and title.
- 2Manage listening progress and bookmarksYou can instruct an agent to update where you left off in a book or create new bookmarks.
- 3Send ebooks to reading devicesAn AI client can facilitate sending ebook files to your connected ereader devices.
- 4Maintain library metadata and coversThe server allows for updating item metadata, covers, and chapter information.
Written from the project's README. Every use case is checked against a quote from it.
How to install Audiobookshelf MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Audiobookshelf MCP in Claude Code
$ claude mcp add --env 'ABS_API_KEY=<YOUR_ABS_API_KEY>' --env 'ABS_BASE_URL=<ABS_BASE_URL>' --env 'ABS_HTTP_BEARER_TOKEN=<YOUR_ABS_HTTP_BEARER_TOKEN>' abs-mcp -- docker run -i --rm ghcr.io/jeeftor/abs-mcp:0.6.0Install Audiobookshelf MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"abs-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/jeeftor/abs-mcp:0.6.0"
],
"env": {
"ABS_API_KEY": "<YOUR_ABS_API_KEY>",
"ABS_BASE_URL": "<ABS_BASE_URL>",
"ABS_HTTP_BEARER_TOKEN": "<YOUR_ABS_HTTP_BEARER_TOKEN>"
}
}
}
}Install Audiobookshelf MCP in VS Code
.vscode/mcp.json
{
"servers": {
"abs-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/jeeftor/abs-mcp:0.6.0"
],
"env": {
"ABS_API_KEY": "<YOUR_ABS_API_KEY>",
"ABS_BASE_URL": "<ABS_BASE_URL>",
"ABS_HTTP_BEARER_TOKEN": "<YOUR_ABS_HTTP_BEARER_TOKEN>"
}
}
}
}Install Audiobookshelf MCP in VS Code CLI
$ code --add-mcp '{"name":"abs-mcp","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/jeeftor/abs-mcp:0.6.0"],"env":{"ABS_API_KEY":"<YOUR_ABS_API_KEY>","ABS_BASE_URL":"<ABS_BASE_URL>","ABS_HTTP_BEARER_TOKEN":"<YOUR_ABS_HTTP_BEARER_TOKEN>"}}'Install Audiobookshelf MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"abs-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/jeeftor/abs-mcp:0.6.0"
],
"env": {
"ABS_API_KEY": "<YOUR_ABS_API_KEY>",
"ABS_BASE_URL": "<ABS_BASE_URL>",
"ABS_HTTP_BEARER_TOKEN": "<YOUR_ABS_HTTP_BEARER_TOKEN>"
}
}
}
}Install Audiobookshelf MCP in Codex
$ codex mcp add abs-mcp --env 'ABS_API_KEY=<YOUR_ABS_API_KEY>' --env 'ABS_BASE_URL=<ABS_BASE_URL>' --env 'ABS_HTTP_BEARER_TOKEN=<YOUR_ABS_HTTP_BEARER_TOKEN>' -- docker run -i --rm ghcr.io/jeeftor/abs-mcp:0.6.0Install Audiobookshelf MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.abs-mcp] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/jeeftor/abs-mcp:0.6.0"] [mcp_servers.abs-mcp.env] ABS_API_KEY = "<YOUR_ABS_API_KEY>" ABS_BASE_URL = "<ABS_BASE_URL>" ABS_HTTP_BEARER_TOKEN = "<YOUR_ABS_HTTP_BEARER_TOKEN>"
Install Audiobookshelf MCP in Gemini CLI
$ gemini mcp add -s user -e 'ABS_API_KEY=<YOUR_ABS_API_KEY>' -e 'ABS_BASE_URL=<ABS_BASE_URL>' -e 'ABS_HTTP_BEARER_TOKEN=<YOUR_ABS_HTTP_BEARER_TOKEN>' abs-mcp docker -- run -i --rm ghcr.io/jeeftor/abs-mcp:0.6.0Install Audiobookshelf MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"abs-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/jeeftor/abs-mcp:0.6.0"
],
"env": {
"ABS_API_KEY": "<YOUR_ABS_API_KEY>",
"ABS_BASE_URL": "<ABS_BASE_URL>",
"ABS_HTTP_BEARER_TOKEN": "<YOUR_ABS_HTTP_BEARER_TOKEN>"
}
}
}
}Audiobookshelf MCP tools 51
Detected from the READMEabs_health_checkabs_list_librariesabs_get_libraryabs_list_library_itemsabs_get_library_itemabs_search_libraryabs_search_ebooksabs_preview_ebook_device_sendabs_get_library_statsabs_get_filter_dataabs_list_library_authorsabs_get_author
Show all 51 toolsShow fewer tools
abs_list_library_seriesabs_get_seriesabs_list_collectionsabs_get_collectionabs_get_items_in_progressabs_get_listening_statsabs_list_listening_sessionsabs_get_item_progressabs_list_bookmarksabs_list_backupsabs_list_ereader_devicesabs_send_ebook_to_deviceabs_send_ebook_by_queryabs_get_item_metadata_objectabs_find_misorganized_itemsabs_scan_libraryabs_scan_library_and_waitabs_scan_itemabs_update_item_metadataabs_update_item_progressabs_create_bookmarkabs_update_bookmarkabs_create_backupabs_update_item_coverabs_remove_item_coverabs_update_item_chaptersabs_create_collectionabs_update_collectionabs_delete_collectionabs_add_collection_itemabs_remove_collection_itemabs_create_playlistabs_update_playlistabs_delete_playlistabs_add_playlist_itemabs_remove_playlist_itemabs_remove_library_items_with_issuesabs_match_itemabs_update_item_tracks
Configuration
ABS_API_KEYRequiredSecretAudiobookshelf API key or bearer token.
ABS_BASE_URLRequiredBase URL of your Audiobookshelf server.
ABS_HTTP_BEARER_TOKENSecretOptional bearer token required from Streamable HTTP MCP clients.
ABS_EXTRA_HEADERS_FILEOptional JSON file containing extra request headers.
ABS_FIXTURE_DIROptional local ABS fixture directory for fixture resources.
ABS_HTTP_ADDRBind address used when ABS_TRANSPORT=http.
ABS_HTTP_PATHStreamable HTTP endpoint path used when ABS_TRANSPORT=http.
ABS_READ_ONLYSet to false to enable scan and cleanup tools.
ABS_TIMEOUTAudiobookshelf request timeout as a Go duration or seconds.
ABS_TLS_CA_CERT_FILEOptional PEM CA bundle for private or corporate ABS TLS.
ABS_TLS_INSECURE_SKIP_VERIFYTemporary TLS verification bypass for local troubleshooting.
ABS_TRANSPORTMCP transport to run at startup. Use stdio for local launchers or http for Streamable HTTP.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablejeeftor/abs-mcp is public and reachablegithub.com/jeeftor/abs-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-16github.com/jeeftor/abs-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model51 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubabs-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
- 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-mcpexposes 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 whenABS_READ_ONLY=false; destructive operations also require exact confirmation strings.michaeldvinci/audiobookshelf-mcpexposes 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-mcpis mostly read/query oriented, with optional progress and bookmark mutation tools that are disabled by default.sierikov/audiobookshelf-mcppresents a read-only browsing, search, progress, stats, author, series, and collection surface.ForceConstant/audiobookshelf_mcpappears 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, andschmidt-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 |
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 |
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 |
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 |
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,
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
.mcpbdesktop bundle packaging. One public peer ships Claude Desktop.mcpbbundles; 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_checkabs_list_librariesabs_get_libraryabs_list_library_itemsabs_get_library_itemabs_search_libraryabs_search_ebooksabs_preview_ebook_device_sendabs_get_library_statsabs_get_filter_dataabs_list_library_authorsabs_get_authorabs_list_library_seriesabs_get_seriesabs_list_collectionsabs_get_collectionabs_get_items_in_progressabs_get_listening_statsabs_list_listening_sessionsabs_get_item_progressabs_list_bookmarksabs_list_backupsabs_list_ereader_devicesabs_send_ebook_to_deviceabs_send_ebook_by_queryabs_get_item_metadata_objectabs_find_misorganized_items
Implemented mutating tools:
abs_scan_libraryabs_scan_library_and_waitabs_scan_itemabs_update_item_metadataabs_update_item_progressabs_create_bookmarkabs_update_bookmarkabs_create_backupabs_update_item_coverabs_remove_item_coverabs_update_item_chaptersabs_create_collectionabs_update_collectionabs_delete_collectionabs_add_collection_itemabs_remove_collection_itemabs_create_playlistabs_update_playlistabs_delete_playlistabs_add_playlist_itemabs_remove_playlist_itemabs_remove_library_items_with_issues
Planned mutating tools advertised for discovery:
abs_match_itemabs_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_send first for device-send UX: it is
read-only, returns compact ebook candidates, sanitized device names, ready,
the exact confirmation string when one ebook and one saved device name resolve,
and nextTool for the send step. ABS still authorizes device access and
delivery during the final device-send call.
Remaining planned mutating tools, including item matching and item track
updates, are advertised for discovery but return a not-implemented error after
read-only checks until their ABS source and fixture behavior is verified.
Resources
abs://server/infoabs://librariesabs://libraries/{library_id}abs://libraries/{library_id}/items?limit=...&offset=...abs://libraries/{library_id}/statsabs://libraries/{library_id}/filterdataabs://items/{item_id}abs://items/{item_id}/metadata-objectabs://api-inventory/currentabs://fixture/status
Prompts
abs_library_auditabs_scan_troubleshootingabs_api_update_review
See docs/tools.md for tool inputs, output shapes, mutation behavior, and common errors.
Configuration
Environment variables and env files are the preferred configuration paths for MCP clients, containers, and other launchers that inject secrets:
export ABS_BASE_URL=http://localhost:13388
export ABS_API_KEY=...
export ABS_READ_ONLY=true
export ABS_TIMEOUT=30s
export ABS_FIXTURE_DIR=test/abs
export ABS_EXTRA_HEADERS_FILE=/path/to/headers.json
export ABS_TLS_CA_CERT_FILE=/path/to/corporate-ca.pem
export ABS_TLS_INSECURE_SKIP_VERIFY=false
export ABS_TRANSPORT=stdio
export ABS_HTTP_ADDR=127.0.0.1:3333
export ABS_HTTP_PATH=/mcp
export ABS_HTTP_BEARER_TOKEN=
The server can load those same values from a Docker-style env file:
go run ./cmd/abs-mcp --env-file /path/to/.env
The server also accepts matching Cobra/Viper CLI flags. Precedence is explicit
CLI flags, then process environment variables, then --env-file, then built-in
defaults:
go run ./cmd/abs-mcp \
--env-file /path/to/.env \
--base-url http://localhost:13388 \
--api-key ... \
--read-only=true \
--timeout 30s \
--fixture-dir test/abs \
--extra-headers-file /path/to/headers.json \
--header 'CF-Access-Client-Id=...' \
--header 'CF-Access-Client-Secret=...' \
--tls-ca-cert-file /path/to/corporate-ca.pem \
--transport stdio \
--http-bearer-token ...
Prefer ABS_API_KEY and ABS_HTTP_BEARER_TOKEN over --api-key and
--http-bearer-token outside short local debugging sessions so tokens do not
land in shell history or process listings.
| Environment variable | CLI flag | Default |
|---|---|---|
| n/a | --env-file |
unset |
ABS_BASE_URL |
--base-url |
required |
ABS_API_KEY |
--api-key |
required |
ABS_READ_ONLY |
--read-only |
true |
ABS_TIMEOUT |
--timeout |
30s |
ABS_FIXTURE_DIR |
--fixture-dir |
test/abs |
ABS_EXTRA_HEADERS_FILE |
--extra-headers-file |
unset |
| n/a | --header NAME=VALUE |
unset |
ABS_TLS_CA_CERT_FILE |
--tls-ca-cert-file |
unset |
ABS_TLS_INSECURE_SKIP_VERIFY |
--tls-insecure-skip-verify |
false |
ABS_TRANSPORT |
--transport |
stdio |
ABS_HTTP_ADDR |
--http-addr |
127.0.0.1:3333 |
ABS_HTTP_PATH |
--http-path |
/mcp |
ABS_HTTP_BEARER_TOKEN |
--http-bearer-token |
unset |
Use ABS_TRANSPORT=http or --transport=http to serve stateless Streamable
HTTP at http://<ABS_HTTP_ADDR><ABS_HTTP_PATH>. The default bind address is
local-only. Each request is independently routable: it does not create or use
an MCP session ID. Proxies must forward the Mcp-Protocol-Version,
Mcp-Method, and Mcp-Name request headers unchanged.
When ABS_HTTP_BEARER_TOKEN is set, HTTP clients must send
Authorization: Bearer <token> to the MCP endpoint. This token protects the MCP
HTTP endpoint and is separate from the upstream ABS_API_KEY sent to
Audiobookshelf. For remote or multi-user access, put the server behind a
TLS/authenticating reverse proxy such as Cloudflare Access / Zero Trust and keep
Audiobookshelf credentials in environment variables or secret files, not URL
query parameters.
ABS_EXTRA_HEADERS_FILE is optional. When set, it must point to a JSON object
of string header names to string values, for example
{"X-Corp-Trace":"trace-1"}. Authorization is rejected there; use
ABS_API_KEY for Audiobookshelf authentication.
--env-file supports simple Docker-style dotenv lines such as KEY=value,
KEY="value", KEY='value', blank lines, comments, and optional export
prefixes. Unknown keys are ignored by the MCP server.
Use --header NAME=VALUE for quick local header injection. It is repeatable,
and duplicate names override values from ABS_EXTRA_HEADERS_FILE. Prefer the
file for secrets such as Cloudflare Access credentials because CLI flags can
show up in shell history and process listings.
For private or corporate TLS certificates, prefer ABS_TLS_CA_CERT_FILE or
--tls-ca-cert-file with a PEM CA bundle. Use
ABS_TLS_INSECURE_SKIP_VERIFY=true or --tls-insecure-skip-verify only as a
temporary fallback while fixing local trust.
Safety
abs-mcp defaults to read-only mode. With ABS_READ_ONLY=true, all mutating
tools are blocked before making Audiobookshelf API calls.
These tools can mutate Audiobookshelf state and require ABS_READ_ONLY=false:
abs_scan_libraryabs_scan_library_and_waitabs_scan_itemabs_update_item_coverabs_remove_item_coverabs_update_item_chaptersabs_update_item_metadataabs_update_item_progressabs_create_bookmarkabs_update_bookmarkabs_create_backupabs_send_ebook_to_deviceabs_send_ebook_by_queryabs_match_item(planned; not implemented)abs_update_item_tracks(planned; not implemented)abs_create_collectionabs_update_collectionabs_delete_collectionabs_add_collection_itemabs_remove_collection_itemabs_create_playlistabs_update_playlistabs_delete_playlistabs_add_playlist_itemabs_remove_playlist_itemabs_remove_library_items_with_issues
The item match and item track tools are stubs: they validate read-only mode, then return a clear not-implemented error until their Audiobookshelf source and Docker fixture behavior are verified.
abs_remove_library_items_with_issues also requires the exact confirmation
string remove issues from <libraryId> and can check an expected issue count
before it asks Audiobookshelf to remove missing or invalid items.
Future destructive tools should follow the same pattern: ABS_READ_ONLY=false
must be necessary but not sufficient, and the tool should require an explicit
confirmation input before deleting, removing, purging, replacing, overwriting,
or broadly batch-mutating Audiobookshelf data.
The server requires an Audiobookshelf base URL and API key or bearer token.
Prefer an Audiobookshelf API key with the least permissions needed for the
tools you plan to expose. Bearer tokens, API keys, raw Authorization headers,
and extra header values are not logged by this server. Authorization is
rejected in ABS_EXTRA_HEADERS_FILE; use ABS_API_KEY for Audiobookshelf
authentication.
Installation
Download a release archive from the
GitHub releases page, unpack it,
and point your MCP client at the abs-mcp binary. The server defaults to MCP
over stdio, which remains the release and registry path.
For local development, you can also run the server from source:
go run ./cmd/abs-mcp
For local Streamable HTTP testing:
ABS_TRANSPORT=http \
ABS_HTTP_ADDR=127.0.0.1:3333 \
ABS_HTTP_PATH=/mcp \
ABS_HTTP_BEARER_TOKEN=dev-mcp-token \
go run ./cmd/abs-mcp
Point Streamable HTTP clients, including local tools such as Hermes or MCP
Inspector, at http://127.0.0.1:3333/mcp. If ABS_HTTP_BEARER_TOKEN is set,
configure the client to send the matching bearer token. The endpoint uses a
static bearer token, not OAuth; deploy OAuth protected-resource metadata only
if the server later adopts an OAuth authorization flow.
Client Configs
Claude Desktop, Cursor, VS Code, and Windsurf all support stdio MCP servers
with a command, arguments, and environment values. Use an absolute binary path
and prefer env or --env-file for secrets.
Claude Desktop claude_desktop_config.json:
{
"mcpServers": {
"Audiobookshelf": {
"command": "/path/to/abs-mcp",
"args": [
"--env-file",
"/path/to/abs-mcp.env",
"--extra-headers-file",
"/path/to/cf-headers.json"
]
}
}
}
Claude Code:
claude mcp add Audiobookshelf /path/to/abs-mcp \
-e ABS_BASE_URL=http://localhost:13378 \
-e ABS_API_KEY=... \
-e ABS_READ_ONLY=true
Cursor mcp.json:
{
"mcpServers": {
"Audiobookshelf": {
"command": "/path/to/abs-mcp",
"env": {
"ABS_BASE_URL": "http://localhost:13378",
"ABS_API_KEY": "...",
"ABS_READ_ONLY": "true"
}
}
}
}
VS Code MCP config:
{
"servers": {
"Audiobookshelf": {
"type": "stdio",
"command": "/path/to/abs-mcp",
"env": {
"ABS_BASE_URL": "http://localhost:13378",
"ABS_API_KEY": "...",
"ABS_READ_ONLY": "true"
}
}
}
}
Windsurf MCP config using an env file:
{
"mcpServers": {
"Audiobookshelf": {
"command": "/path/to/abs-mcp",
"args": [
"--env-file",
"/path/to/abs-mcp.env"
]
}
}
}
Docker-based stdio config:
{
"mcpServers": {
"Audiobookshelf": {
"command": "docker",
"args": [
"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"
],
"env": {
"ABS_API_KEY": "..."
}
}
}
}
Run the container image directly:
docker run --rm -i \
-e ABS_BASE_URL=http://host.docker.internal:13388 \
-e ABS_API_KEY=... \
-e ABS_READ_ONLY=true \
ghcr.io/jeeftor/abs-mcp:0.5.0
With Cloudflare Access headers and a corporate/private CA bundle:
docker run --rm -i \
-e ABS_BASE_URL=https://abs.example.com \
-e ABS_API_KEY=... \
-e ABS_EXTRA_HEADERS_FILE=/run/secrets/abs-headers.json \
-e ABS_TLS_CA_CERT_FILE=/run/secrets/corporate-ca.pem \
-v /path/to/headers.json:/run/secrets/abs-headers.json:ro \
-v /path/to/corporate-ca.pem:/run/secrets/corporate-ca.pem:ro \
ghcr.io/jeeftor/abs-mcp:0.5.0
Build a local image:
make docker-build
Local Development
Bring up the repo-local Audiobookshelf fixture, scan the staged test media, build the MCP server, and write a local MCP client config:
make dev
That target leaves Audiobookshelf running on http://localhost:13388 and writes
.mcp.dev.json. The generated config points at bin/abs-mcp, includes the
fixture token from test/abs/.env.testing, sets ABS_READ_ONLY=true, and is
gitignored.
Use this command when you need mutating scan tools enabled in a local client:
make mcp-dev-config-read-write
Stop the fixture when done:
make abs-dev-down
Install the local pre-commit hooks:
prek install
prek install --hook-type commit-msg
Run all hooks manually:
prek run --all-files
Tests
Run unit and protocol tests:
make test-unit
Run Docker-backed Audiobookshelf integration tests:
make abs-test-integration
The integration target resets and scans the repo-local ABS fixture before running tests.
Stop fixture containers when done:
make abs-dev-down
Audiobookshelf MCP questions
How do I add Audiobookshelf MCP to Claude Code?
Run claude mcp add --env 'ABS_API_KEY=<YOUR_ABS_API_KEY>' --env 'ABS_BASE_URL=<ABS_BASE_URL>' --env 'ABS_HTTP_BEARER_TOKEN=<YOUR_ABS_HTTP_BEARER_TOKEN>' abs-mcp -- docker run -i --rm ghcr.io/jeeftor/abs-mcp:0.6.0 in your terminal. Add --scope user to make it available in every project.
How do I add Audiobookshelf MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Audiobookshelf MCP provide?
It exposes 51 tools, including abs_health_check, abs_list_libraries, abs_get_library, abs_list_library_items, abs_get_library_item.
Is the server read-only by default?
Yes, the server is read-only by default to prevent accidental changes to your library.
How can I enable mutating operations like scanning or metadata updates?
You must set the ABS_READ_ONLY environment variable to false to enable tools that change Audiobookshelf state.
Can I use this to find misorganized books?
Yes, the abs_find_misorganized_items tool audits item paths against supported folder layout conventions without moving or deleting files.