Audiobookshelf MCP Server

A Model Context Protocol (MCP) server written in Rust that bridges AI assistants (like Claude) to a running Audiobookshelf instance.

By integrating this server, your AI assistant can query your libraries, search for audiobooks and podcasts, check listening progress, browse recent sessions, and manage bookmarks — all through Audiobookshelf's REST API.

Features

• Library & Search: List libraries, search by title/author/narrator/series/ISBN, browse paginated items with sorting.
• Progress & Stats: Check what's in progress, view listening statistics, browse playback session history.
• Safety Gates: Mutating tools (progress updates, bookmarks) are disabled by default and must be explicitly enabled.
• Dual Transports: Supports stdio (for local Claude Desktop use) and HTTP/SSE (for remote agentic frameworks).

Requirements

• Audiobookshelf v2.26.0+ (required for API key support)
• An API key generated by an admin in Settings → Users → API Keys

Installation

Requires Rust and Cargo. Build the release binary:

git clone https://github.com/sandymac/audiobookshelf-mcp.git
cd audiobookshelf-mcp
cargo build --release

The binary will be at target/release/audiobookshelf-mcp.

Claude Desktop Configuration

Add to your claude_desktop_config.json:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "audiobookshelf": {
      "command": "/absolute/path/to/target/release/audiobookshelf-mcp",
      "env": {
        "ABS_SERVER_URL": "http://your-server:13378",
        "ABS_API_TOKEN": "your-api-token"
      }
    }
  }
}

Restart Claude Desktop after updating this file.

CLI Usage

audiobookshelf-mcp --server-url http://your-server:13378 --api-token <TOKEN> [OPTIONS]

Flag	Env Var	Default	Description
--server-url <URL>	ABS_SERVER_URL	—	Audiobookshelf base URL
--api-token <TOKEN>	ABS_API_TOKEN	—	API token from Settings → Users → API Keys
--transport <stdio|http>	—	stdio	MCP transport to use
--http-bind <ADDR>	—	127.0.0.1:8080	Bind address for HTTP transport
--http-api-token <TOKEN>	ABS_HTTP_API_TOKEN	—	Bearer token protecting the HTTP/SSE endpoint
--enable-tool <NAME>	—	—	Enable a tool by name (repeatable)
--disable-tool <NAME>	—	—	Disable a tool by name (repeatable, always wins)
--list-tools	—	—	Print all tools with defaults and exit
--test-connection	—	—	Verify API token against /api/me then exit

Use environment variables for credentials to avoid tokens appearing in shell history.

Verify your setup:

audiobookshelf-mcp --server-url http://your-server:13378 --api-token <TOKEN> --test-connection

Tools

Tool	Default	Description
list_libraries	enabled	List all libraries with IDs, names, and media types
search_library	enabled	Search by title, author, narrator, series, or ISBN
get_library_items	enabled	Paginated item list with sorting
get_item	enabled	Full item details including progress, chapters, and files
get_in_progress	enabled	Items currently in progress for the authenticated user
get_listening_stats	enabled	Total time, per-day breakdown, most-listened items
get_recent_sessions	enabled	Recent playback sessions, paginated
update_progress	disabled	Record playback position or mark item finished
create_bookmark	disabled	Create a bookmark at a playback position
delete_bookmark	disabled	Delete a bookmark by its exact time value

update_progress, create_bookmark, and delete_bookmark are disabled by default to prevent unintended mutations. Enable them individually:

audiobookshelf-mcp --server-url ... --api-token ... --enable-tool update_progress --enable-tool create_bookmark

HTTP Transport

For remote or agentic clients, use the HTTP/SSE transport:

audiobookshelf-mcp \
  --server-url http://your-server:13378 \
  --api-token <ABS_TOKEN> \
  --transport http \
  --http-bind 0.0.0.0:8080 \
  --http-api-token "your-secret-bearer-token"

MCP clients connect to http://<host>:8080/mcp with:

Authorization: Bearer your-secret-bearer-token

--http-api-token is strongly recommended whenever binding to a network interface. Without it, anyone who can reach the port can use the server.

For internet-facing deployments, place behind a TLS-terminating reverse proxy (nginx, Caddy, Traefik). The server itself does not handle HTTPS.

Note on Logging

All log output goes to stderr. stdout is reserved for MCP JSON-RPC framing — any output there will corrupt the connection. Log verbosity is controlled via the RUST_LOG environment variable (default: INFO).