Audiobookshelf

audiobookshelf-mcp

セルフホスト型のオーディオブックおよびポッドキャストサーバーである Audiobookshelf 用の Model Context Protocol（MCP）サーバーです。

Claude Code、Claude Desktop、Codex などの MCP クライアントでライブラリを閲覧し、 所有しているものや聴いたものについて質問に答えられます。また、無効にしない限り、 再生状況、ブックマーク、コレクション、プレイリストを最新の状態に保ちます： 読み取りツール 29 個、書き込みツール 15 個の計 44 個です。

44 個のツールは上限であり、最低数ではありません。AUDIOBOOKSHELF_ALLOW_TOOLS=essential を設定すると、厳選された 8 個だけが登録されます。モデルは 44 個より 8 個の中からのほうが 適切なツールをはるかに確実に選べます。詳しくは 読み込むツールの選択をご覧ください。

特長

すべての応答は、生のオブジェクトではなく投影データです。 展開されたライブラリ項目には、 すべての音声ファイル、トラック、チャプターが、完全な ffprobe メタデータとともに含まれます。 メディアツールは代わりにコンパクトな形式で応答し、生のオブジェクトが本当に必要な場合は detail="full" を指定できます。

44 個のツールのうち 29 個は読み取り専用です。 AUDIOBOOKSHELF_READ_ONLY=true を設定すると、それらだけが登録されます。そのため、書き込みツールは呼び出されたときに 拒否されるのではなく、tools/list に表示されません。

何かを取り除く 6 個のツールでは、まず人に確認を求めます。 MCP の elicitation を通じて確認します。これはモデルが人の代わりに回答できないダイアログです。 クライアントがダイアログを表示できない場合は、対象にひも付けられた使い捨てトークンに フォールバックします。

要件

• Node.js 22 以降
• Audiobookshelf 2.26.0 以降 — それ以前のバージョンには API キーがありません
• Audiobookshelf API キー

API キーの取得

API キーは、管理者が Settings → Users → API Keys で管理します。キーは Audiobookshelf のユーザー 1 人の代理として動作し、そのユーザーの権限を継承します。そのため、一般アカウント用に発行されたキーでは、そのアカウントから閲覧できないライブラリは閲覧できず、そのアカウントに削除権限がなければ、何も削除できません。キーが表示されるのは作成時の一度だけです。

設定

変数	必須	説明
AUDIOBOOKSHELF_URL	はい	インスタンスのベース URL。例：https://abs.example.com。認証情報を含めることはできません。
AUDIOBOOKSHELF_API_KEY	はい	API キー。Authorization: Bearer … として送信されます
AUDIOBOOKSHELF_READ_ONLY	いいえ	true を指定すると、読み取り専用の 29 個のツールのみを登録します
AUDIOBOOKSHELF_INSECURE_TLS	いいえ	true を指定すると、自己署名証明書を許可します。この接続のみに適用され、プロセス全体には適用されません
AUDIOBOOKSHELF_ALLOW_TOOLS	いいえ	カンマ区切りのツール名、list_* プレフィックス、または厳選されたプリセットを表す essential
AUDIOBOOKSHELF_DENY_TOOLS	いいえ	同じ構文です。AUDIOBOOKSHELF_ALLOW_TOOLS で残ったツールから除外されます
ELICITATION	いいえ	false を指定すると、承認ダイアログを 2 回呼び出すトークンに置き換えます。プレフィックスは付きません

サーバーは設定なしで起動します。MCP のハンドシェイクを完了してツールを一覧表示し、その後の各呼び出しは設定手順を示して失敗します。これは意図的な動作であり、レジストリやサンドボックスのインスペクターがサーバーを調査できるようにするためです。

読み込むツールの選択

AUDIOBOOKSHELF_ALLOW_TOOLS と AUDIOBOOKSHELF_DENY_TOOLS には、カンマ区切りでツール名を指定します。末尾の * はファミリー全体に一致します。essential は、次の 8 つのツールを厳選したプリセットです：list_libraries、search_library、list_library_items、get_library_item、get_item_chapters、list_items_in_progress、get_media_progress、set_media_progress。

AUDIOBOOKSHELF_ALLOW_TOOLS=essential
AUDIOBOOKSHELF_ALLOW_TOOLS=search_library,get_library_item,set_media_progress
AUDIOBOOKSHELF_DENY_TOOLS=delete_*

どのツールにも一致しない項目があると、その項目名を示して起動を中止します。そのため、タイプミスによってツールが気付かないうちに非表示になることはありません。存在しないツールを環境変数のせいだと後から突き止めるような事態は避けられます。フィルターで除外されたツールは登録されないため、tools/list に表示されず、tools/call でも不明なツールとして扱われます。これは、AUDIOBOOKSHELF_READ_ONLY が有効な場合の書き込みツールと同様です。

このサーバーを複数同時に実行する場合は、もう一つの解決策として mcp-hub があります。その /hub エンドポイントを使うと、各サーバーのツールが 6 つのメタツールに置き換わります。

インストール

Claude Code

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 = "…" }

Docker

SBOM とビルド来歴を含むマルチアーキテクチャ対応：

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

プロトコルは標準入力と標準出力を介して動作するため、-i が必要です。公開するポートはありません。docker run のコマンドラインにキーを表示させない方法など、クライアントの設定例については、クライアントガイドをご覧ください。

mcp-hub 経由

ローカルプロセスを起動できないクライアント（ChatGPT コネクター、Web 版の Claude、 Cursor、LibreChat）は、mcp-hub を通じて audiobookshelf-mcp に接続します。1 つの コンテナーが、複数の stdio MCP サーバーに Streamable HTTP 経由でサービスを提供し、単一のパスワードの背後で OAuth 2.1 ログインを提供します。また、OAuth に対応していないクライアント向けに、長期間有効なトークンも利用できます。/hub エンドポイントは、すべてのサーバーを 6 つのメタツールの背後に配置するため、1 つのコネクターから、モデルのコンテキストに N×ツールのスキーマを含めることなく、すべてのサーバーに接続できます。また、どちらのプロトコルのリビジョンにも対応しており、このサーバーが質問する内容は、そこを通じて相手側のユーザーに届きます。

/config/mcp.json は Claude Code の形式を使用するため、エントリーにはすでに使用しているものを指定します。

{
  "mcpServers": {
    "audiobookshelf": {
      "command": "npx",
      "args": ["-y", "audiobookshelf-mcp"],
      "env": { "AUDIOBOOKSHELF_ALLOW_TOOLS": "essential" },
      "denyTools": ["delete_*"]
    }
  }
}

ここでの allowTools と denyTools は、サーバーごとに設定する hub 独自のフィルターです。env の *_ALLOW_TOOLS とは異なります。この違いと、起こりがちな設定ミスについては、クライアントガイドをご覧ください。

ツール

各ツールは outputSchema を宣言し、テキストブロックに加えて structuredContent も返すため、クライアントは文章を解析せずに結果を利用できます。文だけ（「コレクション col_1 を削除しました。」）を返していた 7 つのツールは、現在、フィールドも返します。

ライブラリのメタデータを報告するツールには、フィールドとして untrusted: true と source: "audiobookshelf" が含まれます。メタデータプロバイダーから取得した書籍の説明、ポッドキャストのフィードの概要やエピソードのタイトルは、すべて第三者が作成したものです。また、アカウントのブックマークのタイトルや選択されたタグ、ライブラリ内で最も長いアイテムと最も大きいアイテムのタイトルも同様です。それ以外のツールにはこのフィールドはありません。そこに含まれるのは、このサーバーに渡された ID、保存するよう依頼された位置、インスタンスのバージョン文字列、オペレーターが入力したライブラリ名やフォルダーパスです。

ドキュメントは、このサーバーが構築するトップレベルキーを持つオープンオブジェクトとして記述されています。detail: "full" を指定すると API レコード全体が返されるため、同じツールでも、名前として列挙されたものよりはるかに多くのキーが返ることがあります。また、SDK は各結果を返す前にスキーマに照らして検証するため、厳密な形式を指定するのは適切ではありません。

get_personalized_shelves は、API が返す配列そのものではなく、{items: [...]} を返します。ルートが配列のスキーマは、2025 年頃のクライアントに提供される際に {result: …} へ書き換えられるため、そうしない場合は 2 種類の形式で返すことになってしまいます。

読む

ツール	説明
list_libraries	アクセス可能なライブラリの ID、名前、メディアタイプ。エントリーポイントです
get_library	フォルダーと設定を含む、1 つのライブラリです
get_library_stats	アイテム数、作者数、ジャンル数、合計再生時間、サイズです
get_library_filter_data	ライブラリで絞り込み可能な値です。作者、ジャンル、タグ、シリーズ、ナレーター、言語、出版社が含まれます
list_library_items	ライブラリのアイテムです。ページ分割、並べ替え、絞り込みが可能です
search_library	書籍、ポッドキャスト、シリーズ、作者、ナレーター、タグを対象とする全文検索です
get_personalized_shelves	ホーム画面の棚です。「続きを聴く」「最近追加」などが含まれます
list_series / get_series	書籍数と合計再生時間を含むシリーズです
list_authors / get_author	作者です。アイテムを含めることもできます
list_tags / list_genres	サーバーで使用されているすべてのタグ／ジャンルです
get_library_item	メタデータ、タグ、再生状況を含む、1 冊の書籍または 1 つのポッドキャストです
get_item_chapters	書籍の章一覧です。長くなることがあるため、個別に取得します
get_podcast_episode	公開日、再生時間、説明を含む、1 つのエピソードです
list_recent_episodes	ポッドキャストライブラリの最新エピソードです
get_me	API キーが使用するユーザーです。権限とライブラリも含まれます
list_items_in_progress	すべてのライブラリで再生を開始したものの、完了していないアイテムです
get_media_progress	1 つのアイテムの再生位置、再生率、完了状態です
get_listening_stats	合計再生時間、日別・曜日別の再生時間、最もよく聴かれたアイテムです
get_year_stats	1 年分の「年間レビュー」の統計情報です
list_listening_sessions	デバイス、再生位置、再生時間を含む再生セッションです
list_bookmarks	すべてのブックマーク、または 1 つのアイテムのブックマークです
list_collections / get_collection	コレクションです。共有可能な、順序付きの書籍グループです
list_playlists / get_playlist	プレイリストです。ユーザーごとに非公開で、書籍またはエピソードを登録できます
get_server_status	サーバーのバージョンと初期化状態です

書き込み

ツール	説明
set_media_progress	再生位置を設定し、再生済みまたは未再生としてマークするか、「続きから聴く」から非表示にします
delete_media_progress 👤	進捗記録（そのアイテムの再生履歴）を削除します
create_bookmark / update_bookmark / delete_bookmark 👤	本の名前付き位置
create_collection / update_collection / delete_collection 👤	コレクション
add_books_to_collection / remove_books_from_collection 👤	コレクションへの追加・削除
create_playlist / update_playlist / delete_playlist 👤	プレイリスト
add_items_to_playlist / remove_items_from_playlist 👤	プレイリストへの追加・削除

👤 は MCP のエリシテーションを通じて人に確認します。クライアントがダイアログを表示できない場合は、2 回の呼び出しで行う confirm_token に切り替わります。

レスポンスサイズ

Audiobookshelf は非常に大きなオブジェクトを返します。展開されたライブラリアイテムには、すべての音声ファイル、トラック、チャプターが完全な ffprobe メタデータ付きで含まれます。そのため、メディアを返すすべてのツールは、デフォルトではコンパクトな投影を返し、未加工のオブジェクトを取得するには detail: "full" を指定します。

上限は 3 つあります。1 つでは足りないためです。

• レスポンスの上限は 5 MB です。 バイトを読み取る前に content-length を確認し、チャンク形式の本文は読み取り中にサイズを数えるため、上限を超えるレスポンスは解析せずに拒否します。
• 結果の上限は 100 000 バイトです。 jsonResult で適用されるため、detail: "full" にも適用されます。切り捨てるのは文字ではなくエントリー全体です。切り詰められたドキュメントは小さなレスポンスではなく、解析不能なレスポンスだからです。その場合、代わりに呼び出すツールを示す truncated ブロックが結果に含まれます。
• 埋め込みメンバー数にも上限があります。 コンパクトなコレクションまたはプレイリストには、書籍またはエントリーの先頭 25 件が埋め込まれ、実際の件数も報告されます。そのうち 1 つの全メンバーを取得するには、get_collection と get_playlist を使います。

list_library_items は limit と page を使って適切にページ分割します。7 つの一覧表示ツール、list_libraries、list_authors、list_tags、list_genres、list_collections、list_playlists、list_bookmarks にはページ分割機能がありません。これらの背後にある Audiobookshelf のルートはすべてを一度に返し、ページ分割パラメーターを受け取らないためです。library_id を指定すると 2 つのコレクション関連ルートを絞り込めます。それ以外は前述の上限が適用されます。

フィルタリング

list_library_items は filter_group と filter_value を受け取り、API が期待する base64 エンコード済みの filter パラメーターを作成します。有効な値は get_library_filter_data から取得します。値を必要とするグループに値が指定されていない場合は拒否します。そうしないと、Audiobookshelf はフィルターなしのライブラリを黙って返すためです。

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)

あえて公開していない機能

再生機能はありません。 一時停止、シーク、再生は、実際のクライアントが担うべきセッション状態の管理です。set_media_progress で「これを再生済みにする」や「第 12 章に移動する」といった操作はできますが、再生するのはお使いのスマートフォンです。

管理機能は、管理者キーを使ってもありません。 ユーザー管理、サーバー設定、バックアップ、キャッシュの消去、ファイルシステムの参照、ライブラリやアイテムの削除、メタデータの書き換え、ファイルのアップロードを行うツールはありません。Audiobookshelf にはこれらのエンドポイントがありますが、ここでは接続していません。誤解したモデルや操作を誘導されたモデルによる影響範囲を、ツール一覧で限定するためです。

安全性

• 読み取り専用モードです。 AUDIOBOOKSHELF_READ_ONLY=true を設定すると、書き込みツールを呼び出し時に拒否するのではなく、そもそも登録しません。

• 人に伝えるだけでなく、確認を求めます。 何かを取り除く可能性のある8つのツール（3つの削除ツール、delete_bookmark、remove_books_from_collection、remove_items_from_playlist、および再並べ替えを求められた場合に元に戻せない順序を置き換える update_collection ／ update_playlist）は、MCP elicitation を通じて実際のダイアログを表示します。モデルが人に代わって回答することはできません。単純な confirm: true フラグなら、モデルが最初の試行で設定したり、ライブラリから返されたテキストに誘導されて設定したりする可能性があります。

  クライアントがダイアログを表示できない場合は、対象を厳密に指定し、5分後に期限切れとなる使い捨てトークンにフォールバックします。このフォールバックで証明できるのは、同じ引数で呼び出しが2回行われたことだけで、それ以上のことは証明できません。そのため、誰かが承認したかのように示すのではなく、その旨をテキストで明記します。ELICITATION=false はこの動作を意図的に選択する設定であり、ガードを取り除くことはありません。人に確認を求めるをご覧ください。

• 確認プロンプトに API の内容を引用することはありません。 コレクション名とプレイリスト名はユーザーが入力したテキストであり、モデルが読み取るため、プロンプトには ID と件数のみを記載します。

• JSON ではない 200 応答はエラーです。 本文を文字列として返すと、インスタンスの前段にある SSO ポータルやキャプティブプロキシが、障害ではなく空のライブラリのように見えてしまいます。

• 信頼できないコンテンツにはラベルを付けます。 書籍の説明はメタデータプロバイダーから、ポッドキャストの要約は RSS フィードから取得するため、第三者が作成したものです。そのようなコンテンツを含む結果にはすべて、指示ではなくデータであることを示すラベルを付けます。

• 設定を読み取った後、API キーは環境から削除されます。 これにより、子プロセスや /proc/<pid>/environ から見えなくなります。

• リダイレクトは追跡しません（redirect: 'error'）。そのため、Authorization ヘッダーが別のホストに対して再利用されることはなく、すべてのリクエストには15秒のタイムアウトが設定されています。

• ID は URL パスに入る前に検証されます。

• アップストリームのエラー本文はサニタイズされます。 HTML のエラーページは破棄し、それ以外は2000文字に切り詰めます。

• 進捗の更新では、許可リストにあるフィールドのみを送信します。 Audiobookshelf のエンドポイントは、ペイロードを進捗レコード全体に適用します。

• 設計上、このサーバーではできないこと： ユーザー管理、サーバー設定、バックアップ、キャッシュの消去、ファイルシステムの閲覧、ライブラリやアイテムの削除、メタデータの書き換え、ファイルのアップロード。

Audiobookshelf 自体に由来する注意点が1つあります。プレイリストの 最後の 項目を削除すると、そのプレイリストも削除されます。この動作が発生した場合、remove_items_from_playlist は結果にその旨を示します。

ドキュメント

完全なガイド、ツールリファレンス、セキュリティに関する注意事項は audiobookshelf-mcp.ni-c.de（ソースは docs/）にあります。

開発

npm install
npm run lint          # oxlint + 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

上の表は手作業で整理したものです。すべてのパラメーターを含む完全な ツールリファレンスはコードから生成され、コミット済みのコピーが古い場合は CI が失敗します。安全に書き込みできる使い捨ての Audiobookshelf については、CONTRIBUTING.mdをご覧ください。書き込みツールは API キーのユーザー自身の進捗状況やブックマークを変更するため、大切なライブラリを使って開発しないでください。

ツール定義は、api.audiobookshelf.orgではなく、Audiobookshelf サーバーのソース（server/routers/ApiRouter.js とコントローラー）をもとに作成しました。API ドキュメントは複数の点で古くなっています。フィルターデータのエンドポイントは /filter ではなく /filterdata、進捗の更新は POST /api/me/progress ではなく PATCH /api/me/progress/:id、ブックマークは /api/me/item/:id/bookmark にあります。

リリース

タグをトリガーとするため、手動で公開する手順はありません。

1. CHANGELOG.md の [Unreleased] の項目を、新しい ## [x.y.z] - YYYY-MM-DD セクションに移し、package.json のバージョンを更新します。
2. npm run lint && npm run build && npm run test:coverage を実行します。
3. コミットしてから、署名付きの注釈付きタグを作成します：git tag -s vx.y.z -m "vx.y.z"。
4. git push origin main vx.y.z を実行します。

その後、release.yml がテストを実行し、Trusted Publishing による来歴情報付きで npm に公開します（トークンシークレットは不要です）。さらに、CHANGELOG の該当セクションをもとに GitHub リリースを作成し、[MCP registry](https://registry.modelcontextprotocol.io) に io.github.ni-c/audiobookshelf-mcp として公開します。同じタグで、ci.yml はマルチアーキテクチャイメージを GHCR にプッシュします。

レジストリのステップが失敗した場合は、main で修正してから Publish to MCP Registry ワークフローをディスパッチしてください。古いツリーがチェックアウトされるため、タグのジョブを再実行してはいけません。

コントリビューション

Issue、ディスカッション、プルリクエストを歓迎します。詳しくは CONTRIBUTING.md をご覧ください。脆弱性については、公開 Issue ではなく 非公開での報告 をご利用ください。ポリシーは SECURITY.md に記載されています。

ライセンス

MIT © Willi Thiel