Audiobookshelf

Audiobookshelf MCP Server

A Model Context Protocol server for Audiobookshelf - gives AI assistants access to your self-hosted audiobook and podcast library.

MCP Registry name: mcp-name: io.github.sierikov/audiobookshelf-mcp

What can it do?

Ask your AI assistant things like:

• "What am I currently listening to?"
• "Search for Dune in my library"
• "What are my listening stats?"
• "What did I listen to recently?"
• "How far am I in Katabasis?"
• "What libraries do I have?"

Tools

Default toolsets: libraries, items, playback. The browse, chapters and metadata toolsets are opt-in via AUDIOBOOKSHELF_TOOLSETS.

Fixing chapters

With the chapters toolset enabled, ask things like *"Fix the chapters for Katabasis"*. The assistant reads the book's current chapters, searches Audible for the edition whose runtime matches your files, fetches its chapters, replaces generic titles ("Chapter 1, 2, 3") with real ones, and shows you the list before saving. When Audible has no match, it can build the list from its own research or from timestamps you give it. Every save returns the previous chapters, so a change can be undone, as long as those old chapters were valid (old chapters that run past the end of the book, for example, cannot be saved back).

Cleaning up genres, tags and descriptions

With the metadata toolset enabled, ask things like *"Make my genres consistent"* or *"Fix the descriptions of the Harry Hole books"*. The assistant surveys the library with get_metadata_overview, proposes a mapping from the old genres or tags to the new ones, and shows you the affected books. After you say yes, it adds the new value first and then removes the old one, so no book is left without it. For descriptions it looks up real ones with search_book_metadata, shows each change from old to new, and tells you when it wrote a description itself. Every write returns what it changed, so a change can be undone: the genre and tag tools list each book's added or removed values, and update_items returns the previous values.

---

Install in Claude Desktop (one-click)

Download the .mcpb bundle for your platform, open it, and Claude Desktop will walk you through setup.

The .mcpb format is currently only supported by Claude Desktop. Other clients use the manual setup below.

---

Manual setup (all other clients)

1. Get your API token

Audiobookshelf → Settings → Users → your user → API Token

2. Install the binary

go install:

go install github.com/sierikov/audiobookshelf-mcp/cmd/audiobookshelf-mcp@latest

Download and install to `/usr/local/bin`:

macOS (Apple Silicon)

curl -L https://github.com/sierikov/audiobookshelf-mcp/releases/latest/download/audiobookshelf-mcp-macos-arm64 \

-o /usr/local/bin/audiobookshelf-mcp && chmod +x /usr/local/bin/audiobookshelf-mcp

macOS (Intel)

curl -L https://github.com/sierikov/audiobookshelf-mcp/releases/latest/download/audiobookshelf-mcp-macos-amd64 \

-o /usr/local/bin/audiobookshelf-mcp && chmod +x /usr/local/bin/audiobookshelf-mcp

Linux (x64)

curl -L https://github.com/sierikov/audiobookshelf-mcp/releases/latest/download/audiobookshelf-mcp-linux-amd64 \

-o /usr/local/bin/audiobookshelf-mcp && chmod +x /usr/local/bin/audiobookshelf-mcp

Linux (arm64)

curl -L https://github.com/sierikov/audiobookshelf-mcp/releases/latest/download/audiobookshelf-mcp-linux-arm64 \

-o /usr/local/bin/audiobookshelf-mcp && chmod +x /usr/local/bin/audiobookshelf-mcp

Windows

Download audiobookshelf-mcp-windows-amd64.exe, rename to audiobookshelf-mcp.exe, and place it in a directory on your %PATH% (e.g. C:\Program Files\audiobookshelf-mcp\).

3. Configure your client

Claude Code

claude mcp add audiobookshelf \

-e AUDIOBOOKSHELF_URL=https://abs.example.com \ -e AUDIOBOOKSHELF_TOKEN=your-token \ -- audiobookshelf-mcp

Antigravity CLI (formerly Gemini CLI)

antigravity --add-mcp '{"name":"audiobookshelf","command":"audiobookshelf-mcp","env":{"AUDIOBOOKSHELF_URL":"https://abs.example.com","AUDIOBOOKSHELF_TOKEN":"your-token"}}'

OpenCode

Add to ~/.config/opencode/config.json:

{

"mcpServers": { "audiobookshelf": { "type": "stdio", "command": "audiobookshelf-mcp", "args": [], "env": { "AUDIOBOOKSHELF_URL": "https://abs.example.com", "AUDIOBOOKSHELF_TOKEN": "your-token" } } } }

---

Configuration

---

Security

The default toolsets are read-only. Two opt-in toolsets write, and both need an API token whose user has the Update permission in Audiobookshelf. Neither needs admin.

• chapters: set_chapters and rename_chapters replace a book's chapters. They are annotated as destructive so MCP clients ask before running them, and return the previous chapters so a change can be undone when those old chapters were valid.
• metadata: add_genres, remove_genres, add_tags and remove_tags add and remove genres and tags, and update_items sets language and description. The remove tools and update_items are annotated as destructive. Every write can be undone: the list tools by calling the opposite tool with each book's added or removed values, update_items by passing the previous values it returns. Audiobookshelf can limit what a user sees by tag, so add_tags and remove_tags can change what a restricted user, such as a kids account, can see.

all includes every write tool; list toolsets explicitly to stay read-only. No tool deletes items, controls playback, or manages users. The API token is passed via environment variable, never logged or exposed.

License

MIT