Audiobookshelf MCP Server

A Go MCP server for inspecting and safely operating Audiobookshelf libraries.

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.

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; Streamable HTTP is a good future fit 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-05-20

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, metadata-object, layout-audit, resources, and prompts by default. Scan, cleanup, cover, and chapter 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, and stats 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:

#2: Add playback progress and bookmark MCP tools. Other servers expose progress/session inspection, and sandymac/audiobookshelf-mcp exposes optional progress/bookmark mutations.
#3: Add richer author, series, and collection read tools. Public peers expose broader browsing in these areas than this server currently documents.
#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.
#5: Investigate Streamable HTTP transport support. Public peers include HTTP/SSE or generated Streamable HTTP variants, while this server currently focuses on stdio.

Server	Shape	Confirmed strengths	Safety posture	Difference from `jeeftor/abs-mcp`
`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. No public evidence was found for a misorganized-file audit, source-backed API inventory, MCP resources/prompts, cover removal/update, or chapter update tooling.
`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, but narrower feature scope. No public evidence was found for metadata, cover, chapter repair tools, organizer-oriented audits, or fixture/API-inventory workflows.
`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.	Useful inspection surface, but not a controlled repair workflow. No public evidence was found for mutating metadata, cover, chapter, cleanup, or organizer-focused audit tooling.
`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, were excluded when no implementation or feature evidence was available.

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.1.1

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 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_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_cover
abs_remove_item_cover
abs_update_item_chapters
abs_remove_library_items_with_issues

Planned mutating tools advertised for discovery:

abs_update_item_metadata
abs_match_item
abs_update_item_tracks
abs_create_collection
abs_update_collection
abs_delete_collection
abs_add_collection_item
abs_remove_collection_item
abs_create_playlist
abs_update_playlist
abs_delete_playlist
abs_add_playlist_item
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, and abs_update_item_chapters are implemented. Remaining planned mutating tools, including broad metadata updates and item matching, are advertised for discovery but return a not-implemented error after read-only and confirmation checks until their ABS source and fixture behavior are verified.

Resources

abs://server/info
abs://libraries
abs://libraries/{library_id}
abs://libraries/{library_id}/items?limit=...&offset=...
abs://libraries/{library_id}/stats
abs://libraries/{library_id}/filterdata
abs://items/{item_id}
abs://items/{item_id}/metadata-object
abs://api-inventory/current
abs://fixture/status

Prompts

abs_library_audit
abs_scan_troubleshooting
abs_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

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

Prefer ABS_API_KEY over --api-key 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_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_library
abs_scan_library_and_wait
abs_scan_item
abs_update_item_cover
abs_remove_item_cover
abs_update_item_chapters
abs_update_item_metadata (planned; not implemented)
abs_match_item (planned; not implemented)
abs_update_item_tracks
abs_create_collection
abs_update_collection
abs_delete_collection
abs_add_collection_item
abs_remove_collection_item
abs_create_playlist
abs_update_playlist
abs_delete_playlist
abs_add_playlist_item
abs_remove_playlist_item
abs_remove_library_items_with_issues

The newly advertised item, collection, and playlist mutation tools are stubs: they validate read-only mode and destructive confirmations, 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 speaks MCP over stdio.

For local development, you can also run the server from source:

go run ./cmd/abs-mcp

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.1.1"
      ],
      "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.1.1

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.1.1

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

CI and Releases

GitHub Actions runs unit tests, Go package tests, a binary build, and a Docker image build on pushes and pull requests to master.

Tags matching v* publish release archives for Linux, macOS, and Windows on amd64 and arm64. The release workflow also publishes a multi-arch Docker image to ghcr.io/jeeftor/abs-mcp.

MCP Registry

This repository is prepared for the official MCP Registry using the OCI package path:

Registry name: io.github.jeeftor/abs-mcp
Package: ghcr.io/jeeftor/abs-mcp:<version>
Transport: stdio
Metadata file: server.json

The Docker image includes the required MCP ownership label io.modelcontextprotocol.server.name=io.github.jeeftor/abs-mcp.

On v* tags, the release workflow builds the immutable GHCR image tag, rewrites server.json to the tag version, authenticates to the MCP Registry with GitHub OIDC, and publishes with mcp-publisher. GitHub OIDC does not require a dedicated registry secret.

After the official registry entry is published, downstream aggregators can pick it up from the registry API. Glama is the next practical listing target. Smithery should wait until this project either ships an MCPB bundle for stdio distribution or adds a public Streamable HTTP transport with appropriate auth.

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.agents/skills		.agents/skills
.github/workflows		.github/workflows
cmd/abs-mcp		cmd/abs-mcp
docs		docs
internal		internal
scripts		scripts
skills-agent-ai-configs		skills-agent-ai-configs
test/abs		test/abs
.conventional-pre-commit-config.yaml		.conventional-pre-commit-config.yaml
.dockerignore		.dockerignore
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
PLAN.md		PLAN.md
README.md		README.md
go.mod		go.mod
go.sum		go.sum
server.json		server.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Audiobookshelf MCP Server

Table of Contents

Highlights

Audiobook Organizer Compatibility

AI Generated Comparison - Last updated 2026-05-20

Quick Start

MCP Surface

Tools

Resources

Prompts

Configuration

Safety

Installation

Client Configs

Local Development

Tests

CI and Releases

MCP Registry

About

Uh oh!

Releases 3

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Audiobookshelf MCP Server

Table of Contents

Highlights

Audiobook Organizer Compatibility

AI Generated Comparison - Last updated 2026-05-20

Quick Start

MCP Surface

Tools

Resources

Prompts

Configuration

Safety

Installation

Client Configs

Local Development

Tests

CI and Releases

MCP Registry

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages