Audiobookshelf MCP Server

A Model Context Protocol (MCP) server for Audiobookshelf — gives AI assistants read-only access to your audiobook and podcast library.

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

Tool	Description	Toolset
list_libraries	List all libraries	libraries
search_library	Search by title, author, or narrator	libraries
list_library_items	List items with pagination	libraries
get_item	Get detailed info about an audiobook or podcast	items
get_items_in_progress	Get currently listening items with progress	items
get_listening_stats	Total listening time and daily breakdown	playback
get_listening_sessions	Recent listening sessions	playback
get_media_progress	Progress for a specific item	playback
list_series	List all series in a library	browse
get_series	Get series details with books	browse
get_author	Get author details with books	browse
list_collections	List collections in a library	browse

Default toolsets: libraries, items, playback. The browse toolset is opt-in.

Setup

1. Get your API token

Audiobookshelf web UI → Settings → Users → your user → API Token

2. Install

From source:

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

From release binary:

Download from Releases and place in your $PATH.

Linux (amd64)

curl -L https://github.com/sierikov/audiobookshelf-mcp/releases/latest/download/audiobookshelf-mcp-linux-amd64 -o audiobookshelf-mcp
chmod +x audiobookshelf-mcp

Linux (arm64)

curl -L https://github.com/sierikov/audiobookshelf-mcp/releases/latest/download/audiobookshelf-mcp-linux-arm64 -o audiobookshelf-mcp
chmod +x audiobookshelf-mcp

macOS (Apple Silicon / arm64)

curl -L https://github.com/sierikov/audiobookshelf-mcp/releases/latest/download/audiobookshelf-mcp-macos-arm64 -o audiobookshelf-mcp
chmod +x audiobookshelf-mcp

macOS (Intel / amd64)

curl -L https://github.com/sierikov/audiobookshelf-mcp/releases/latest/download/audiobookshelf-mcp-macos-amd64 -o audiobookshelf-mcp
chmod +x audiobookshelf-mcp

Windows (amd64)

Download audiobookshelf-mcp-windows-amd64.exe, rename it to audiobookshelf-mcp.exe, and add it to a directory in your %PATH%.

3. Configure your AI client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "audiobookshelf": {
      "command": "audiobookshelf-mcp",
      "env": {
        "AUDIOBOOKSHELF_URL": "https://abs.example.com",
        "AUDIOBOOKSHELF_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Code

claude mcp add audiobookshelf -- env AUDIOBOOKSHELF_URL=https://abs.example.com AUDIOBOOKSHELF_TOKEN=your-api-token audiobookshelf-mcp

Or add to .mcp.json in your project:

{
  "mcpServers": {
    "audiobookshelf": {
      "command": "audiobookshelf-mcp",
      "env": {
        "AUDIOBOOKSHELF_URL": "https://abs.example.com",
        "AUDIOBOOKSHELF_TOKEN": "your-api-token"
      }
    }
  }
}

VS Code / Cursor / Windsurf

Add to your settings JSON (mcp section):

{
  "mcp": {
    "servers": {
      "audiobookshelf": {
        "command": "audiobookshelf-mcp",
        "env": {
          "AUDIOBOOKSHELF_URL": "https://abs.example.com",
          "AUDIOBOOKSHELF_TOKEN": "your-api-token"
        }
      }
    }
  }
}

OpenCode

Add to your OpenCode config:

{
  "mcp": {
    "audiobookshelf": {
      "type": "local",
      "command": "audiobookshelf-mcp",
      "env": {
        "AUDIOBOOKSHELF_URL": "https://abs.example.com",
        "AUDIOBOOKSHELF_TOKEN": "your-api-token"
      }
    }
  }
}

Configuration

Environment Variable	Required	Description
AUDIOBOOKSHELF_URL	Yes	Your Audiobookshelf server URL
AUDIOBOOKSHELF_TOKEN	Yes	API token (Bearer token)
AUDIOBOOKSHELF_TOOLSETS	No	Comma-separated toolsets to enable (default: libraries,items,playback)

To enable all toolsets including browse:

AUDIOBOOKSHELF_TOOLSETS=libraries,items,playback,browse

Build from source

git clone https://github.com/sierikov/audiobookshelf-mcp.git
cd audiobookshelf-mcp
go build -o audiobookshelf-mcp ./cmd/audiobookshelf-mcp

Cross-compile:

GOOS=linux   GOARCH=amd64 go build -o audiobookshelf-mcp-linux-amd64       ./cmd/audiobookshelf-mcp
GOOS=linux   GOARCH=arm64 go build -o audiobookshelf-mcp-linux-arm64       ./cmd/audiobookshelf-mcp
GOOS=darwin  GOARCH=amd64 go build -o audiobookshelf-mcp-macos-amd64       ./cmd/audiobookshelf-mcp
GOOS=darwin  GOARCH=arm64 go build -o audiobookshelf-mcp-macos-arm64       ./cmd/audiobookshelf-mcp
GOOS=windows GOARCH=amd64 go build -o audiobookshelf-mcp-windows-amd64.exe ./cmd/audiobookshelf-mcp

Security

• All tools are read-only — no writes, no playback control, no user management
• The API token is passed via environment variable, never logged or exposed
• All tool definitions include readOnlyHint: true annotation

License

MIT