Audiobookshelf MCP

CLI or API | MCP

Documentation — Installation, deployment, usage across the API, CLI, and MCP backing platform are maintained in the official documentation.

Overview

Audiobookshelf API client + MCP Server

The package exposes an operator-selected Audiobookshelf service through typed, action-routed tools without storing an endpoint, credential, or instance profile.

This repository is actively maintained - Contributions are welcome!

Key Features

Action-routed MCP tools — each domain is exposed as a single MCP tool that routes to multiple underlying operations via an action argument, keeping the tool surface small.
Two interfaces, one package — use it as a Python API client, an MCP server (stdio / streamable-http / sse).
scion-sdk native — built on the shared framework (auth, action router, telemetry, governance) for fleet consistency.
Checked transport profiles — outbound HTTP uses AgentConfig-backed TLS trust; peer and hostname verification cannot be disabled by this connector.
Governed graph capability inputs — ships one complete skill, a public-model ontology, and a neutral source preset, but no direct graph-write or raw-media tool.
Per-tool toggles — enable or disable each tool domain with environment switches.
Enterprise-ready — OTEL/Langfuse telemetry and optional Eunomia access governance.

Available MCP Tools

Each tool is action-routed: pass an action and a JSON params_json payload. Tool domains can be toggled on or off with the listed environment variable. The table below is auto-generated from the live server by the mcp-readme-table pre-commit hook (python -m scion_sdk.mcp.readme_tools) — do not edit it by hand.

Condensed action-routed tools (`MCP_TOOL_MODE=condensed`)

MCP Tool	Toggle Env Var	Description
`author_operations`	`AUTHORSTOOL`	Manage Audiobookshelf authors. CONCEPT:AS-OS.identity.abs-2
`email_operations`	`EMAILTOOL`	Manage Audiobookshelf email settings and e-reader delivery. CONCEPT:AS-OS.governance.abs-3
`library_operations`	`LIBRARIESTOOL`	Manage Audiobookshelf libraries. CONCEPT:AS-OS.identity.abs
`notification_operations`	`NOTIFICATIONTOOL`	Manage Audiobookshelf notifications. CONCEPT:AS-OS.governance.abs-4
`podcast_operations`	`PODCASTSTOOL`	Manage Audiobookshelf podcasts and episodes. CONCEPT:AS-OS.governance.abs-2
`series_operations`	`SERIESTOOL`	Manage Audiobookshelf series. CONCEPT:AS-OS.governance.abs

Verbose 1:1 API-mapped tools (`MCP_TOOL_MODE=verbose` or `both`)

46 per-operation tools — one per public API method (click to expand)

MCP Tool	Toggle Env Var	Description
`audiobookshelf_add_author_image_by_id`	`AUTHORSTOOL`	Upload/add an author's image by id.
`audiobookshelf_bulk_create_podcasts_from_opml_feed`	`PODCASTSTOOL`	Bulk create podcasts from an OPML feed.
`audiobookshelf_check_new_episodes`	`PODCASTSTOOL`	Check for new episodes for a podcast by id.
`audiobookshelf_clear_episode_download_queue`	`PODCASTSTOOL`	Clear the episode download queue for a podcast by id.
`audiobookshelf_configure_notification_settings`	`NOTIFICATIONTOOL`	Update the global notification settings.
`audiobookshelf_create_library`	`LIBRARIESTOOL`	Create a new library.
`audiobookshelf_create_notification`	`NOTIFICATIONTOOL`	Create a new notification.
`audiobookshelf_create_podcast`	`PODCASTSTOOL`	Create a new podcast library item.
`audiobookshelf_delete_author_by_id`	`AUTHORSTOOL`	Delete an author by id.
`audiobookshelf_delete_author_image_by_id`	`AUTHORSTOOL`	Remove an author's image by id.
`audiobookshelf_delete_library_by_id`	`LIBRARIESTOOL`	Delete a library by id.
`audiobookshelf_delete_library_issues`	`LIBRARIESTOOL`	Remove all library items that have issues from a library.
`audiobookshelf_delete_notification`	`NOTIFICATIONTOOL`	Delete a notification by id.
`audiobookshelf_download_episodes`	`PODCASTSTOOL`	Queue episodes for download for a podcast by id.
`audiobookshelf_find_episode`	`PODCASTSTOOL`	Search for a podcast episode by id.
`audiobookshelf_get_author_by_id`	`AUTHORSTOOL`	Get a single author by id (supports include/library params).
`audiobookshelf_get_author_image_by_id`	`AUTHORSTOOL`	Get an author's image by id.
`audiobookshelf_get_email_settings`	`EMAILTOOL`	Get the server email settings.
`audiobookshelf_get_episode`	`PODCASTSTOOL`	Get a single podcast episode by id.
`audiobookshelf_get_episode_downloads`	`PODCASTSTOOL`	Get the current episode download queue for a podcast by id.
`audiobookshelf_get_feeds_from_opml_text`	`PODCASTSTOOL`	Parse feeds from raw OPML text.
`audiobookshelf_get_libraries`	`LIBRARIESTOOL`	List all libraries.
`audiobookshelf_get_library_authors`	`LIBRARIESTOOL`	Get the authors within a library.
`audiobookshelf_get_library_by_id`	`LIBRARIESTOOL`	Get a single library by id.
`audiobookshelf_get_library_items`	`LIBRARIESTOOL`	Get the items within a library (supports limit/page/sort/filter params).
`audiobookshelf_get_library_series`	`LIBRARIESTOOL`	Get the series within a library.
`audiobookshelf_get_library_series_by_id`	`LIBRARIESTOOL`	Get a single series within a library by id.
`audiobookshelf_get_notification_event_data`	`NOTIFICATIONTOOL`	Get the available notification event data.
`audiobookshelf_get_notifications`	`NOTIFICATIONTOOL`	Get the configured notification settings and notifications.
`audiobookshelf_get_podcast_feed`	`PODCASTSTOOL`	Fetch a podcast RSS feed by URL.
`audiobookshelf_get_series`	`SERIESTOOL`	Get a single series by id (supports include params).
`audiobookshelf_match_author_by_id`	`AUTHORSTOOL`	Match an author against a metadata provider by id.
`audiobookshelf_quick_match_episodes`	`PODCASTSTOOL`	Quick-match a podcast's episodes against a feed by id.
`audiobookshelf_remove_episode`	`PODCASTSTOOL`	Remove a podcast episode by id.
`audiobookshelf_send_default_test_notification`	`NOTIFICATIONTOOL`	Send a default test notification.
`audiobookshelf_send_ebook_to_device`	`EMAILTOOL`	Send an ebook to a configured e-reader device.
`audiobookshelf_send_test_email`	`EMAILTOOL`	Send a test email using the configured settings.
`audiobookshelf_send_test_notification`	`NOTIFICATIONTOOL`	Send a test notification for a specific notification by id.
`audiobookshelf_update_author_by_id`	`AUTHORSTOOL`	Update an author by id.
`audiobookshelf_update_author_image_by_id`	`AUTHORSTOOL`	Update an author's image by id.
`audiobookshelf_update_email_settings`	`EMAILTOOL`	Update the server email settings.
`audiobookshelf_update_episode`	`PODCASTSTOOL`	Update a podcast episode by id.
`audiobookshelf_update_ereader_devices`	`EMAILTOOL`	Update the configured e-reader devices.
`audiobookshelf_update_library_by_id`	`LIBRARIESTOOL`	Update a library by id.
`audiobookshelf_update_notification`	`NOTIFICATIONTOOL`	Update a notification by id.
`audiobookshelf_update_series`	`SERIESTOOL`	Update a series by id.

6 action-routed tool(s) · 46 verbose 1:1 tool(s). Each is enabled unless its <DOMAIN>TOOL toggle is set false; MCP_TOOL_MODE selects the surface (intent default — the six verb-tools, granular set loaded on demand · condensed action-routed · verbose 1:1 · both). Auto-generated — do not edit.

Installation

Install with `uvx` (no install — run on demand)

uvx --from "audiobookshelf-mcp[mcp]" audiobookshelf-mcp      # MCP server

Install with `pip` / `uv`

Pick the extra that matches what the operator want to run:

Extra	Installs	Use when
`audiobookshelf-mcp[mcp]`	MCP server (`scion-sdk`) plus the mandatory full medulla base runtime	The operator run the MCP server
`audiobookshelf-mcp[all]`	MCP + test tooling	Development

# MCP server only (recommended for tool hosting)
uv pip install "audiobookshelf-mcp[mcp]"

# Everything (development)
uv pip install "audiobookshelf-mcp[all]"      # or: python -m pip install "audiobookshelf-mcp[all]"

Container images (`:mcp`)

One multi-stage docker/Dockerfile builds the MCP-only image (--target mcp):

Image tag	Build target	Contents	Entrypoint
`audiobookshelf-mcp:mcp`	`--target mcp`	MCP server plus the mandatory full medulla base dependency	`audiobookshelf-mcp`

docker build --target mcp -t audiobookshelf-mcp:mcp -f docker/Dockerfile .

Knowledge-graph database (`medulla`)

Every install receives medulla[full] through the current Scion SDK base dependency. The connector does not open an insecure engine listener or silently select a machine-specific engine. Deployment topology and identity are resolved by AgentConfig. For a shared production authority, follow the medulla deployment guide.

Console scripts

After installation the following entry points are available on the operator's PATH:

Command	Description
`audiobookshelf-mcp`	Start the MCP server

Usage

As a Python API client

from audiobookshelf_mcp.auth import get_client

client = get_client()
try:
    print(client.get_libraries())
finally:
    client.close()

As an MCP server (CLI)

# Local stdio (for IDEs)
audiobookshelf-mcp

# Networked streamable-http
audiobookshelf-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Calling an MCP tool

Tools are action-routed — pass an action plus a JSON params_json string:

{
  "tool": "library_operations",
  "arguments": {
    "action": "list",
    "params_json": "{}"
  }
}

MCP

MCP Configuration Examples

Install the connector-focused [mcp] extra. Examples use audiobookshelf-mcp[mcp] to add FastMCP / FastAPI through scion-sdk; the required Scion SDK core still carries medulla[full]. The [agent-runtime] extra additionally enables model orchestration.

stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)

{
  "mcpServers": {
    "audiobookshelf-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "audiobookshelf-mcp[mcp]",
        "audiobookshelf-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "intent",
        "AUDIOBOOKSHELF_TOKEN": "env://AUDIOBOOKSHELF_TOKEN",
        "AUDIOBOOKSHELF_URL": "env://AUDIOBOOKSHELF_URL",
        "AUTHORSTOOL": "True",
        "EMAILTOOL": "True",
        "LIBRARIESTOOL": "True",
        "NOTIFICATIONTOOL": "True",
        "PODCASTSTOOL": "True",
        "SERIESTOOL": "True"
      }
    }
  }
}

Runtime references require an alias-aware launcher such as Arbora. Other launchers must omit those entries and inject the resolved values through their own runtime secret boundary.

Streamable-HTTP Transport (networked / production)

{
  "mcpServers": {
    "audiobookshelf-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "audiobookshelf-mcp[mcp]",
        "audiobookshelf-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "127.0.0.1",
        "PORT": "8000",
        "MCP_TOOL_MODE": "intent",
        "AUDIOBOOKSHELF_TOKEN": "env://AUDIOBOOKSHELF_TOKEN",
        "AUDIOBOOKSHELF_URL": "env://AUDIOBOOKSHELF_URL",
        "AUTHORSTOOL": "True",
        "EMAILTOOL": "True",
        "LIBRARIESTOOL": "True",
        "NOTIFICATIONTOOL": "True",
        "PODCASTSTOOL": "True",
        "SERIESTOOL": "True"
      }
    }
  }
}

Alternatively, connect to a pre-deployed Streamable-HTTP instance by url:

{
  "mcpServers": {
    "audiobookshelf-mcp": {
      "url": "http://localhost:8000/audiobookshelf-mcp/mcp"
    }
  }
}

Run a reviewed container image as a least-privilege stdio child (no listener or published port):

docker run -i --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --pids-limit=256 \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  -e TRANSPORT=stdio \
  -e MCP_TOOL_MODE=intent \
  -e AUDIOBOOKSHELF_TOKEN \
  -e AUDIOBOOKSHELF_URL \
  -e AUTHORSTOOL=True \
  -e EMAILTOOL=True \
  -e LIBRARIESTOOL=True \
  -e NOTIFICATIONTOOL=True \
  -e PODCASTSTOOL=True \
  -e SERIESTOOL=True \
  registry.example.invalid/audiobookshelf-mcp@sha256:<digest> audiobookshelf-mcp

For containerized network HTTP, supply an authenticated TLS ingress (or direct server TLS), exact MCP_ALLOWED_HOSTS, and an exact trusted-proxy CIDR policy through the operator-owned deployment profile. The generator does not emit an unauthenticated non-loopback listener.

Auto-generated from the code-read env surface (MCP_TOOL_MODE + package vars) — do not edit.

Additional Deployment Options

audiobookshelf-mcp can run as a local stdio process or container, or behind a remote network boundary. The Deployment guide carries the detailed transport contract.

Local container — launch a reviewed immutable image as a least-privilege stdio child with no listener or published port.
Remote URL — connect through an operator-supplied authenticated HTTPS ingress. Keep its URL, outbound identity references, trust profile, and exact MCP_ALLOWED_HOSTS in AgentConfig.

Environment Variables

Package environment variables

Variable	Example	Description
`HOST`	`127.0.0.1`
`PORT`	`8000`
`TRANSPORT`	`stdio`	options: stdio, streamable-http, sse
`MCP_TOOL_MODE`	`intent`	options: intent, condensed, verbose, both
`ENABLE_OTEL`	`False`
`OTEL_EXPORTER_OTLP_ENDPOINT`	`env://OTEL_EXPORTER_OTLP_ENDPOINT`	runtime endpoint
`OTEL_EXPORTER_OTLP_HEADERS_REF`	`secret://telemetry/headers`	runtime header reference
`OTEL_EXPORTER_OTLP_PROTOCOL`	`http/protobuf`	OTLP transport protocol
`LANGFUSE_CAPTURE_CONTENT`	`false`
`EUNOMIA_TYPE`	`none`	options: none, embedded, remote
`EUNOMIA_POLICY_FILE`	—
`EUNOMIA_REMOTE_URL`	`env://EUNOMIA_REMOTE_URL`	runtime policy endpoint
`AUDIOBOOKSHELF_URL`	`env://AUDIOBOOKSHELF_URL`	resolved by the fleet launcher
`AUDIOBOOKSHELF_TOKEN`	secret-injected	secret provider or delegation
`LIBRARIESTOOL`	`True`
`AUTHORSTOOL`	`True`
`SERIESTOOL`	`True`
`PODCASTSTOOL`	`True`
`EMAILTOOL`	`True`
`NOTIFICATIONTOOL`	`True`

Inherited scion-sdk variables (apply to every connector)

Variable	Example	Description
`MCP_ENABLED_TOOLS`	—	Comma-separated tool allow-list
`MCP_DISABLED_TOOLS`	—	Comma-separated tool deny-list
`MCP_ENABLED_TAGS`	—	Comma-separated tag allow-list
`MCP_DISABLED_TAGS`	—	Comma-separated tag deny-list
`MCP_CLIENT_AUTH`	—	Outbound MCP child auth: `oidc-client-credentials` \| `basic` \| `none`
`OIDC_CLIENT_ID`	—	OIDC client id (service-account auth)
`OIDC_CLIENT_SECRET_REF`	`secret://identity/oidc-client-secret`	Runtime secret reference for the OIDC service account
`MCP_BASIC_AUTH_USERNAME`	—	HTTP Basic username (`MCP_CLIENT_AUTH=basic`)
`MCP_BASIC_AUTH_PASSWORD_REF`	`secret://identity/mcp-basic-password`	Runtime secret reference for HTTP Basic auth (`MCP_CLIENT_AUTH=basic`)
`DEBUG`	`False`	Verbose logging
`PYTHONUNBUFFERED`	`1`	Unbuffered stdout (recommended in containers)
`MCP_URL`	`http://localhost:8000/mcp`	URL of the MCP server the agent connects to
`PROVIDER`	`openai`	LLM provider for the agent
`MODEL_ID`	`gpt-4o`	Model id for the agent
`ENABLE_WEB_UI`	`True`	Serve the AG-UI web interface

20 package + 15 inherited variable(s). Auto-generated from .env.example + the shared scion-sdk set — do not edit.

The generated table is the authoritative process-variable catalog. Endpoint and credential examples are unresolved references, not deployment values. AgentConfig owns TLS selection, OIDC delegation, runtime secret resolution, and observability policy; see Configuration, trust, and privacy for those typed profiles.

Documentation

Full documentation is published to the GitHub Pages site and mirrored under docs/:

Governed capability contract

This package owns the complete release-generated schema-v2 capability bundle: connector_manifest.yml, the exact local MCP schema fingerprint, the Audiobookshelf ontology, SHACL shapes, the neutral source mapping and fixture, the migration ledger, and an offline source attestation. Release tooling derives and signs these artifacts from the current tool and ontology sources; they are not hand-authored and do not claim external-live certification.

Runtime endpoints, credentials, certificate trust, identity, tenant/ACL policy, retention, and observability destinations are deployment inputs and are never packaged values. See Configuration, trust, and privacy before enabling a network transport, Arbora delegation, governed source synchronization, or trace export.

Name		Name	Last commit message	Last commit date
.github		.github
.specify/memory		.specify/memory
audiobookshelf_mcp		audiobookshelf_mcp
docker		docker
docs		docs
scripts		scripts
specs		specs
tests		tests
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.vulture_ignore		.vulture_ignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
mcp_config.json		mcp_config.json
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
uv.lock		uv.lock

Navigation Menu

Repository navigation

About

Repository files navigation

Audiobookshelf MCP

CLI or API | MCP

Table of Contents

Overview

Key Features

Available MCP Tools

Condensed action-routed tools (`MCP_TOOL_MODE=condensed`)

Verbose 1:1 API-mapped tools (`MCP_TOOL_MODE=verbose` or `both`)

Installation

Install with `uvx` (no install — run on demand)

Install with `pip` / `uv`

Container images (`:mcp`)

Knowledge-graph database (`medulla`)

Console scripts

Usage

As a Python API client

As an MCP server (CLI)

Calling an MCP tool

MCP

MCP Configuration Examples

stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)

Streamable-HTTP Transport (networked / production)

Additional Deployment Options

Environment Variables

Package environment variables

Inherited scion-sdk variables (apply to every connector)

Documentation

Governed capability contract

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Audiobookshelf MCP

CLI or API | MCP

Table of Contents

Overview

Key Features

Available MCP Tools

Condensed action-routed tools (MCP_TOOL_MODE=condensed)

Verbose 1:1 API-mapped tools (MCP_TOOL_MODE=verbose or both)

Installation

Install with uvx (no install — run on demand)

Install with pip / uv

Container images (:mcp)

Knowledge-graph database (medulla)

Console scripts

Usage

As a Python API client

As an MCP server (CLI)

Calling an MCP tool

MCP

MCP Configuration Examples

stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)

Streamable-HTTP Transport (networked / production)

Additional Deployment Options

Environment Variables

Package environment variables

Inherited scion-sdk variables (apply to every connector)

Documentation

Governed capability contract

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Condensed action-routed tools (`MCP_TOOL_MODE=condensed`)

Verbose 1:1 API-mapped tools (`MCP_TOOL_MODE=verbose` or `both`)

Install with `uvx` (no install — run on demand)

Install with `pip` / `uv`

Container images (`:mcp`)

Knowledge-graph database (`medulla`)