Audiobookshelf MCP Server

audiobookshelf-mcp

An MCP server for Audiobookshelf, the self-hosted audiobook and podcast server. It lets an AI assistant browse your libraries, answer questions about what you own and what you have listened to, and — unless you switch it off — keep your listening progress, bookmarks, collections and playlists up to date.

44 tools: 29 read, 15 write.

📖 Full documentation: https://audiobookshelf-mcp.ni-c.de

Requirements

• Node.js 22 or newer
• Audiobookshelf 2.26.0 or newer — earlier versions have no API keys
• An Audiobookshelf API key

Getting an API key

API keys are managed by an admin under Settings → Users → API Keys. A key acts on behalf of exactly one Audiobookshelf user and inherits that user's permissions, so a key issued for a normal account cannot see libraries that account cannot see, and cannot delete anything unless that account may delete. The key is shown only once, at creation.

Configuration

The server starts without configuration: it completes the MCP handshake and lists its tools, and every call then fails with the setup instructions. That is deliberate, so registries and sandbox inspectors can introspect it.

Install

claude mcp add audiobookshelf \
  -e AUDIOBOOKSHELF_URL=https://abs.example.com \
  -e AUDIOBOOKSHELF_API_KEY=… \
  -- npx -y audiobookshelf-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "audiobookshelf": {
      "command": "npx",
      "args": ["-y", "audiobookshelf-mcp"],
      "env": {
        "AUDIOBOOKSHELF_URL": "https://abs.example.com",
        "AUDIOBOOKSHELF_API_KEY": "…"
      }
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.audiobookshelf]
command = "npx"
args = ["-y", "audiobookshelf-mcp"]
env = { AUDIOBOOKSHELF_URL = "https://abs.example.com", AUDIOBOOKSHELF_API_KEY = "…" }

Container (multi-arch, with SBOM and build provenance):

docker run -i --rm \
  -e AUDIOBOOKSHELF_URL=https://abs.example.com \
  -e AUDIOBOOKSHELF_API_KEY=… \
  ghcr.io/ni-c/audiobookshelf-mcp

-i is required — the protocol runs over stdin and stdout. There is no port to publish. More client recipes, including how to keep the key off the docker run command line, are in the client guide.

Tools

Reading

Writing

Response size

Audiobookshelf returns very large objects — an expanded library item carries every audio file, track and chapter with full ffprobe metadata. Every tool that returns media therefore answers with a compact projection by default and accepts detail: "full" for the raw object. List tools are capped at 100 entries per call and say how to page on when more match.

Filtering

list_library_items takes filter_group plus filter_value and builds the base64-encoded filter parameter the API expects. The valid values come from get_library_filter_data. A valued group without a value is rejected, because Audiobookshelf would silently answer with the unfiltered library instead.

filter_group="authors",  filter_value="<author id>"
filter_group="progress", filter_value="finished" | "in-progress" | "not-started" | "not-finished"
filter_group="issues"    (standalone, no value)

Safety

• Read-only mode. AUDIOBOOKSHELF_READ_ONLY=true does not register the write tools at all, rather than refusing them at call time.
• Confirmation tokens. delete_collection, delete_playlist and delete_media_progress answer the first call with a single-use token that is bound to the target id and expires after five minutes; only a second call carrying that token performs the deletion. A plain confirm: true flag could be set by the model on the first try, or be talked into it by text coming out of the library. Operations that are cheap to undo — removing an item from a collection, deleting a bookmark — are marked destructive but do not require a token.
• Confirmation prompts never quote API content. Collection and playlist names are user-supplied text and are read by a model, so the prompts name only ids.
• Untrusted content is marked. Book descriptions come from metadata providers and podcast summaries come from RSS feeds — third parties write them. Every result carrying such content is labelled as data, not instructions.
• The API key is deleted from the environment once the configuration has been read, so it is not visible to child processes or in /proc/<pid>/environ.
• No redirects are followed (redirect: 'error'), so the Authorization header cannot be replayed against another host, and every request has a 15 second timeout.
• Ids are validated before they enter a URL path.
• Upstream error bodies are sanitized: HTML error pages are dropped, anything else is truncated to 2000 characters.
• Progress updates send whitelisted fields only. The Audiobookshelf endpoint applies its payload to the progress record wholesale.
• What this server cannot do, by design: no user management, no server settings, no backups, no cache purging, no filesystem browsing, no library or item deletion, no metadata rewriting, no file uploads.

One caveat that comes from Audiobookshelf itself: removing the last entry from a playlist deletes the playlist. remove_items_from_playlist says so in its result when it happens.

Development

npm install
npm run lint          # eslint + prettier --check
npm run build         # tsc
npm test              # vitest
npm run test:coverage # with thresholds
npm run docs:tools    # regenerate docs/reference/tools.md from the registered tools

The table above is hand-curated; the complete tool reference with every parameter is generated from the code, and CI fails if the committed copy is stale. See CONTRIBUTING.md for a throwaway Audiobookshelf you can safely write to — the write tools change progress and bookmarks on the API key's own user, so don't develop against a library you care about.

The tool definitions were derived from the Audiobookshelf server source (server/routers/ApiRouter.js and the controllers) rather than from api.audiobookshelf.org, which is out of date in several places — the filter data endpoint is /filterdata not /filter, progress updates are PATCH /api/me/progress/:id not POST /api/me/progress, and bookmarks live under /api/me/item/:id/bookmark.

Releasing

Tag-driven, no manual publish step:

1. Move the [Unreleased] entries into a new ## [x.y.z] - YYYY-MM-DD section in CHANGELOG.md and bump package.json.
2. npm run lint && npm run build && npm run test:coverage.
3. Commit, then a signed annotated tag: git tag -s vx.y.z -m "vx.y.z".
4. git push origin main vx.y.z.

release.yml then runs the tests, publishes to npm with provenance via Trusted Publishing (no token secret involved), creates the GitHub release from the CHANGELOG section, and publishes to the MCP registry as io.github.ni-c/audiobookshelf-mcp. ci.yml pushes the multi-arch image to GHCR on the same tag.

If the registry step fails, fix it on main and dispatch the Publish to MCP Registry workflow — do not re-run the tag job, which would check out the old tree.

Contributing

Issues, discussions and pull requests are welcome — see CONTRIBUTING.md. For vulnerabilities please use private reporting rather than a public issue; the policy is in SECURITY.md.

License

MIT