Audiobookshelf MCP

Audiobookshelf MCP サーバー

Audiobookshelf ライブラリを調査し、安全に操作するための Go 製 MCP サーバーです。

abs-mcp は、Audiobookshelf ライブラリの調査、スキャンの診断、および必要に応じて範囲を限定したメンテナンスワークフローの実行を行うエージェント向けに、安全で型付けされた MCP ツールとリソースを提供します。

目次

• 主な特徴
• Audiobook Organizer との互換性
• AI 生成の比較 - 最終更新日 2026-06-22
• クイックスタート
• MCP の機能
• 設定
• 安全性
• インストール
  • クライアント設定
• ローカル開発
• テスト
• CI とリリース
• MCP レジストリ

主な特徴

• デフォルトでは読み取り専用です。スキャンツールとクリーンアップツールには ABS_READ_ONLY=false が必要です。
• 単一の Go バイナリまたは Docker イメージで、ローカルの stdio MCP サーバーとして動作します。ホスト環境や複数クライアントでのデプロイ向けに、Streamable HTTP モードも任意で利用できます。
• 環境変数、Docker 形式の env ファイル、追加ヘッダー、カスタム TLS CA バンドルに対応しています。
• ソースに基づく Audiobookshelf API インベントリリソースと、繰り返し実行できるフィクスチャテストを含みます。
• 公式 MCP レジストリのメタデータに適したリリースバイナリと GHCR イメージを公開しています。

Audiobook Organizer との互換性

この MCP サーバーは、特に jeeftor/audiobook-organizer と併用できるように作成しました。ライブラリ、アイテム、メタデータ、サーバーの状態を調査する標準的な Audiobookshelf MCP ツールを提供する一方で、特に便利なワークフローの 1 つは、書籍がディスク上で期待どおりに整理されているかを監査することです。

abs_find_misorganized_items ツールは、作成者／タイトルや作成者／シリーズ／タイトルなど、対応するフォルダー構成規則に照らして Audiobookshelf のアイテムパスをチェックします。監査専用のため、ファイルを移動または削除せずに、設定に問題がある、または配置が間違っている可能性のある書籍を報告します。そのため、Audiobook Organizer と組み合わせるのに適しています。この MCP サーバーで Audiobookshelf の観点からフォルダー構成の問題を特定し、その後、Audiobook Organizer で実際のファイルを整理または標準化できます。

AI 生成の比較 - 最終更新日 2026-06-22

この比較は、公開されている GitHub リポジトリのメタデータ、プロジェクトの公開 README、レジストリやパッケージの検索結果、およびこのリポジトリの現在のドキュメントに基づいて生成されています。推奨ではなく、説明を目的としています。

変更を伴う機能と変更を伴わない機能の対応状況：

• jeeftor/abs-mcp は、デフォルトで読み取り専用の検査、検索、作成者、シリーズ、コレクション、現在のユーザーの進捗状況／ブックマーク／再生状況の読み取り、バックアップ、電子書籍リーダーデバイスの検出、電子書籍の送信プレビュー、メタデータオブジェクト、レイアウト監査、リソース、プロンプトを公開します。電子書籍デバイスへの送信ツールは外部への配信を行いますが、Audiobookshelf のライブラリ、メタデータ、バックアップ、進捗状況、コレクション、プレイリストの状態は変更しないため、読み取り専用モードでも使用できます。スキャン、クリーンアップ、カバー、チャプター、進捗状況／ブックマークの書き込み、バックアップの作成、メタデータ、コレクション／プレイリストの作成／更新／追加／削除／除去ツールが Audiobookshelf の状態を変更できるのは、ABS_READ_ONLY=false の場合に限られます。破壊的な操作には、正確な確認文字列も必要です。
• michaeldvinci/audiobookshelf-mcp は、読み取りツールに加え、ライブラリ、コレクション、プレイリスト、進捗状況、バックアップに関する操作など、幅広い管理機能を公開します。今回の確認では、グローバルなデフォルトの読み取り専用ゲートに関する公開 README の記載は見つかりませんでした。
• sandymac/audiobookshelf-mcp は主に読み取り／クエリ指向で、進捗状況やブックマークを変更するオプションのツールはデフォルトで無効です。
• sierikov/audiobookshelf-mcp は、読み取り専用のブラウジング、検索、進捗状況、統計、作成者、シリーズ、コレクション機能を提供します。
• ForceConstant/audiobookshelf_mcp は Audiobookshelf の OpenAPI 情報から生成されたものと思われますが、変更操作の対応範囲と安全性のゲートは公開 README からは判断できません。

今回の確認で参照した情報源：

• 公開 GitHub リポジトリ： michaeldvinci/audiobookshelf-mcp、 sandymac/audiobookshelf-mcp、 sierikov/audiobookshelf-mcp、 ForceConstant/audiobookshelf_mcp、 および schmidt-software/mcp-audiobookshelf。
• npm と PyPI で追加のパッケージを検索しましたが、上記の GitHub リポジトリ以外に、Audiobookshelf 専用の信頼できる MCP サーバーは見つかりませんでした。 | サーバー | 形式 | 確認された強み | 安全性の方針 | jeeftor/abs-mcp との違い | | --- | --- | --- | --- | --- | | michaeldvinci/audiobookshelf-mcp | リリースバイナリを提供する Go の stdio サーバーです。GitHub のメタデータでは、最新リリース 0.0.5 は 2025-11-11 でした。 | ライブラリ、アイテム、著者、コレクション、プレイリスト、ユーザー情報、セッション、ポッドキャスト、進捗の更新、バックアップなど、Audiobookshelf の幅広い汎用管理機能を提供します。 | 変更を行うツールを公開しています。この比較時点で、公開 README には、全体に適用されるデフォルトの読み取り専用制限は見つかりませんでした。 | より幅広い汎用管理機能を提供しますが、より慎重な設計ではありません。このサーバーでは、型付きの修復・カタログワークフローがさらに拡充され、デフォルトの読み取り専用制限、破壊的操作の確認、ソースに基づく API インベントリ、MCP リソース／プロンプト、整理担当者向けの監査ツール、フィクスチャに基づく動作チェックも追加されています。 | | sandymac/audiobookshelf-mcp | stdio と HTTP/SSE に対応する Rust サーバーです。 | ライブラリ、検索、進捗、統計、最近のセッションを読み取り／クエリでき、オプションで進捗やブックマークの変更も可能です。 | 変更を行うツールはデフォルトで無効になっており、明示的に有効化する必要があります。HTTP モードでは、Bearer 認証と TLS プロキシの使用が推奨されています。 | 類似した安全性モデルです。変更機能を限定的に保っています。このサーバーでは、ソースに基づく API インベントリ、リソース／プロンプト、整理担当者向けの監査、フィクスチャを使ったワークフロー、型付きのメタデータ／カバー画像／チャプター／カタログツール、明示的な破壊的操作の確認が追加されています。 | | sierikov/audiobookshelf-mcp | 読み取り中心のツールを備えた Go サーバーです。リリースバイナリ、.mcpb Claude Desktop バンドル、MCP Registry エントリも提供しています。 | ライブラリ、アイテム、進捗、統計、セッション、シリーズ、著者、コレクションを対象とした読み取り専用の閲覧と検索が可能です。 | 公開 README では、すべてのツールを読み取り専用とし、書き込み、再生制御、ユーザー管理は行わないと説明しています。 | 進捗、著者、シリーズ、コレクションの読み取りなど、このサーバーの読み取り専用の閲覧機能と重複します。一方、制御された修復／カタログ変更ワークフロー、ソースに基づく API インベントリ、MCP プロンプト／リソース、整理担当者向けの監査ツール、Docker フィクスチャワークフローを示す公開情報は見つかりませんでした。 | | ForceConstant/audiobookshelf_mcp | Streamable HTTP をポート 3000 で提供する、生成された OpenAPI MCP ブリッジです。Docker 向けのファイルもあります。 | Audiobookshelf の OpenAPI 資料から生成された、幅広い API を公開します。 | 公開 README からは判断できません。生成された API には変更を行うエンドポイントが含まれる可能性がありますが、README には安全性の制御方法が列挙されていません。 | 厳選度が低く、運用担当者に特化していません。このプロジェクトでは、すべてのルートを直接公開するのではなく、読み取り専用の制限とフィクスチャに基づく動作チェックを備えた、範囲を限定した型付きツールを意図的に公開しています。 |

schmidt-software/mcp-audiobookshelf のように、実装や機能を裏付ける情報がない弱い候補やプレースホルダー的な候補は除外しました。

この比較から見つかった候補の不足点

• 候補：範囲を限定したポッドキャストのワークフローを評価します。公開されている同種のサーバーでは、ポッドキャストの閲覧やエピソードの確認ができますが、このサーバーには現在、汎用のアイテム／ライブラリ API 以外にポッドキャスト専用のツールはありません。
• 候補：ライブラリの作成／更新ワークフローを評価します。公開されている同種のサーバーの1つではライブラリの作成ができますが、これは依然として管理者レベルの操作であり、ソースの検証、フィクスチャのカバレッジ、ABS_READ_ONLY=false、および削除／除去を伴う処理に対する破壊的操作の確認が必要です。
• 候補：.mcpb デスクトップバンドルのパッケージ化を評価します。公開されている同種のサーバーの1つは Claude Desktop 用の .mcpb バンドルを提供していますが、このサーバーは現在、バイナリ、Docker/GHCR アーティファクト、MCP Registry のメタデータを公開しています。
• 既存の候補も引き続き関連があります： #5 では Streamable HTTP トランスポートのサポートを追跡しています。公開されている同種のサーバーでは HTTP/SSE と Streamable HTTP の両方の形式が見られるため、この課題を現在のオプションの Streamable HTTP 実装と、残っている強化点やドキュメントの不足点に照らして再検討する必要があります。

クイックスタート

ダウンロードしたリリースバイナリを MCP stdio 経由で実行します：

ABS_BASE_URL=http://localhost:13378 \
ABS_API_KEY=... \
ABS_READ_ONLY=true \
/path/to/abs-mcp

または、コンテナイメージを実行します：

docker run --rm -i \
  -e ABS_BASE_URL=http://host.docker.internal:13378 \
  -e ABS_API_KEY=... \
  -e ABS_READ_ONLY=true \
  ghcr.io/jeeftor/abs-mcp:0.5.0

クライアント固有のスニペットについては、クライアント設定を参照してください。

MCP サーフェス

ツール

サーバーは、Audiobookshelf の状態を変更できるかどうかで分類した、登録済みのすべてのツールを README に公開しています。

読み取り専用で、ABS を変更しないツール：

• abs_health_check
• abs_list_libraries
• abs_get_library
• abs_list_library_items
• abs_get_library_item
• abs_search_library
• abs_search_ebooks
• abs_preview_ebook_device_send
• abs_get_library_stats
• abs_get_filter_data
• abs_list_library_authors
• abs_get_author
• abs_list_library_series
• abs_get_series
• abs_list_collections
• abs_get_collection
• abs_get_items_in_progress
• abs_get_listening_stats
• abs_list_listening_sessions
• abs_get_item_progress
• abs_list_bookmarks
• abs_list_backups
• abs_list_ereader_devices
• abs_send_ebook_to_device
• abs_send_ebook_by_query
• abs_get_item_metadata_object
• abs_find_misorganized_items

実装済みの変更ツール：

• abs_scan_library
• abs_scan_library_and_wait
• abs_scan_item
• abs_update_item_metadata
• abs_update_item_progress
• abs_create_bookmark
• abs_update_bookmark
• abs_create_backup
• abs_update_item_cover
• abs_remove_item_cover
• abs_update_item_chapters
• abs_create_collection
• abs_update_collection
• abs_delete_collection
• abs_add_collection_item
• abs_remove_collection_item
• abs_create_playlist
• abs_update_playlist
• abs_delete_playlist
• abs_add_playlist_item
• abs_remove_playlist_item
• abs_remove_library_items_with_issues

検出用に公開されている、実装予定の変更ツール：

• abs_match_item
• abs_update_item_tracks

Audiobookshelf の状態を変更するツールは、ABS_READ_ONLY のデフォルト値が true であるため、デフォルトでブロックされます。スキャンツール、問題のある項目のクリーンアップ、カバーの更新、チャプターの更新、型付きアイテムメタデータ、現在のユーザーの進捗やブックマークの書き込み、バックアップの作成、コレクションやプレイリストの作成、更新、項目の追加、削除、項目の削除を行うツールは、実装済みの変更操作です。電子書籍のデバイスへの送信、およびガード付きのクエリベースのデバイス送信は、既存の電子書籍ファイルをメールで送信するだけであり、Audiobookshelf の状態（ライブラリ、メタデータ、バックアップ、進捗、コレクション、プレイリスト）を作成、変更、削除しません。そのため、読み取り専用モードが有効でも使用できます。ここでいう読み取り専用とは、「Audiobookshelf の状態を変更しない」という意味であり、「外部への副作用を一切発生させない」という意味ではありません。デバイスへの送信を完全に抑止する必要がある場合は、電子書籍リーダーのデバイスを設定しないでください。デバイス送信の UX には、まず abs_preview_ebook_device_send を使用してください。このツールは読み取り専用で、簡潔な電子書籍候補、サニタイズされたデバイス名、ready、電子書籍 1 冊と保存済みデバイス名 1 件に解決された場合の正確な確認文字列、および送信手順の nextTool を返します。ABS は、最終的なデバイス送信の呼び出し時にデバイスへのアクセスと送信を引き続き承認します。 アイテムの照合やアイテムのトラック更新など、残りの実装予定の変更ツールは検出用に公開されていますが、ABS のソースとフィクスチャの動作が検証されるまでは、読み取り専用チェック後に未実装エラーを返します。

リソース

• abs://server/info
• abs://libraries
• abs://libraries/{library_id}
• abs://libraries/{library_id}/items?limit=...&offset=...
• abs://libraries/{library_id}/stats
• abs://libraries/{library_id}/filterdata
• abs://items/{item_id}
• abs://items/{item_id}/metadata-object
• abs://api-inventory/current
• abs://fixture/status

プロンプト

• abs_library_audit
• abs_scan_troubleshooting
• abs_api_update_review

ツールの入力、出力形式、変更動作、および一般的なエラーについては、docs/tools.md を参照してください。

設定

シークレットを注入する MCP クライアント、コンテナ、その他のランチャーでは、環境変数と環境ファイルを優先して設定してください。

export ABS_BASE_URL=http://localhost:13388
export ABS_API_KEY=...
export ABS_READ_ONLY=true
export ABS_TIMEOUT=30s
export ABS_FIXTURE_DIR=test/abs
export ABS_EXTRA_HEADERS_FILE=/path/to/headers.json
export ABS_TLS_CA_CERT_FILE=/path/to/corporate-ca.pem
export ABS_TLS_INSECURE_SKIP_VERIFY=false
export ABS_TRANSPORT=stdio
export ABS_HTTP_ADDR=127.0.0.1:3333
export ABS_HTTP_PATH=/mcp
export ABS_HTTP_BEARER_TOKEN=

サーバーは、Docker 形式の環境ファイルから同じ値を読み込むこともできます。

go run ./cmd/abs-mcp --env-file /path/to/.env

サーバーでは、対応する Cobra/Viper CLI フラグも使用できます。優先順位は、明示的な CLI フラグ、プロセス環境変数、--env-file、組み込みのデフォルト値の順です。

go run ./cmd/abs-mcp \
  --env-file /path/to/.env \
  --base-url http://localhost:13388 \
  --api-key ... \
  --read-only=true \
  --timeout 30s \
  --fixture-dir test/abs \
  --extra-headers-file /path/to/headers.json \
  --header 'CF-Access-Client-Id=...' \
  --header 'CF-Access-Client-Secret=...' \
  --tls-ca-cert-file /path/to/corporate-ca.pem \
  --transport stdio \
  --http-bearer-token ...

トークンがシェルの履歴やプロセス一覧に残らないよう、短時間のローカルデバッグ以外では、--api-key や --http-bearer-token よりも ABS_API_KEY と ABS_HTTP_BEARER_TOKEN を優先してください。

環境変数	CLI フラグ	デフォルト
n/a	--env-file	未設定
ABS_BASE_URL	--base-url	必須
ABS_API_KEY	--api-key	必須
ABS_READ_ONLY	--read-only	true
ABS_TIMEOUT	--timeout	30s
ABS_FIXTURE_DIR	--fixture-dir	test/abs
ABS_EXTRA_HEADERS_FILE	--extra-headers-file	未設定
n/a	--header NAME=VALUE	未設定
ABS_TLS_CA_CERT_FILE	--tls-ca-cert-file	未設定
ABS_TLS_INSECURE_SKIP_VERIFY	--tls-insecure-skip-verify	false
ABS_TRANSPORT	--transport	stdio
ABS_HTTP_ADDR	--http-addr	127.0.0.1:3333
ABS_HTTP_PATH	--http-path	/mcp
ABS_HTTP_BEARER_TOKEN	--http-bearer-token	未設定

ABS_TRANSPORT=http または --transport=http を指定すると、ステートレスな Streamable HTTP を http://<ABS_HTTP_ADDR><ABS_HTTP_PATH> で提供します。デフォルトのバインドアドレスはローカル専用です。各リクエストは個別にルーティングされ、MCP セッション ID の作成や使用はありません。プロキシでは、リクエストヘッダー Mcp-Protocol-Version、Mcp-Method、Mcp-Name を変更せずに転送する必要があります。 ABS_HTTP_BEARER_TOKEN が設定されている場合、HTTP クライアントは MCP エンドポイントに Authorization: Bearer <token> を送信する必要があります。このトークンは MCP HTTP エンドポイントを保護するもので、Audiobookshelf に送信される上流向けの ABS_API_KEY とは別です。リモートアクセスや複数ユーザーでのアクセスでは、サーバーを Cloudflare Access / Zero Trust などの TLS 対応・認証機能付きリバースプロキシの背後に配置し、Audiobookshelf の認証情報は URL クエリパラメーターではなく、環境変数またはシークレットファイルに保存してください。

ABS_EXTRA_HEADERS_FILE は任意です。設定する場合は、文字列のヘッダー名を文字列の値に対応付けた JSON オブジェクトを指定する必要があります。例：{"X-Corp-Trace":"trace-1"}。ここでは Authorization は使用できません。Audiobookshelf の認証には ABS_API_KEY を使用してください。

--env-file は、KEY=value、KEY="value"、KEY='value' のようなシンプルな Docker 形式の dotenv 行、空行、コメント、および省略可能な export 接頭辞に対応しています。不明なキーは MCP サーバーによって無視されます。

手早くローカルでヘッダーを注入するには、--header NAME=VALUE を使用してください。これは繰り返し指定でき、重複する名前は ABS_EXTRA_HEADERS_FILE の値を上書きします。Cloudflare Access の認証情報などのシークレットには、CLI フラグがシェルの履歴やプロセス一覧に表示される可能性があるため、ファイルを使用してください。

プライベートまたは企業内の TLS 証明書には、PEM CA バンドルを指定して ABS_TLS_CA_CERT_FILE または --tls-ca-cert-file を使用してください。ローカルの信頼設定を修正する間の一時的な代替手段としてのみ、ABS_TLS_INSECURE_SKIP_VERIFY=true または --tls-insecure-skip-verify を使用してください。

安全性

abs-mcp はデフォルトで読み取り専用モードです。ABS_READ_ONLY=true の場合、変更を伴うすべてのツールは Audiobookshelf API を呼び出す前にブロックされます。

以下のツールは Audiobookshelf の状態を変更するため、ABS_READ_ONLY=false が必要です。

• abs_scan_library
• abs_scan_library_and_wait
• abs_scan_item
• abs_update_item_cover
• abs_remove_item_cover
• abs_update_item_chapters
• abs_update_item_metadata
• abs_update_item_progress
• abs_create_bookmark
• abs_update_bookmark
• abs_create_backup
• abs_send_ebook_to_device
• abs_send_ebook_by_query
• abs_match_item（予定。未実装）
• abs_update_item_tracks（予定。未実装）
• abs_create_collection
• abs_update_collection
• abs_delete_collection
• abs_add_collection_item
• abs_remove_collection_item
• abs_create_playlist
• abs_update_playlist
• abs_delete_playlist
• abs_add_playlist_item
• abs_remove_playlist_item
• abs_remove_library_items_with_issues

アイテムの照合ツールとトラックツールはスタブです。読み取り専用モードを検証した後、Audiobookshelf のソースと Docker フィクスチャの動作が確認されるまで、明確な未実装エラーを返します。

abs_remove_library_items_with_issues では、確認文字列 remove issues from <libraryId> を正確に指定する必要があります。また、Audiobookshelf に存在しないアイテムや無効なアイテムの削除を依頼する前に、想定される問題の件数を確認できます。

今後追加される破壊的なツールも、同じパターンに従う必要があります。ABS_READ_ONLY=false は必要条件ではあっても十分条件ではありません。Audiobookshelf のデータを削除、除去、完全消去、置換、上書き、または広範囲に一括変更する場合、ツールは明示的な確認入力を必須にする必要があります。

サーバーを利用するには、Audiobookshelf のベース URL と API キーまたはベアラートークンが必要です。公開するツールに必要な最小限の権限を持つ Audiobookshelf API キーを使用してください。ベアラートークン、API キー、生の Authorization ヘッダー、および追加のヘッダー値は、このサーバーではログに記録されません。ABS_EXTRA_HEADERS_FILE では Authorization は拒否されます。Audiobookshelf の認証には ABS_API_KEY を使用してください。

インストール

GitHub リリースページからリリースアーカイブをダウンロードして展開し、MCP クライアントで abs-mcp バイナリを指定します。サーバーはデフォルトで stdio 経由の MCP を使用します。これはリリースとレジストリで引き続き使用される方式です。

ローカル開発では、ソースからサーバーを実行することもできます。

go run ./cmd/abs-mcp

ローカルで Streamable HTTP をテストする場合：

ABS_TRANSPORT=http \
ABS_HTTP_ADDR=127.0.0.1:3333 \
ABS_HTTP_PATH=/mcp \
ABS_HTTP_BEARER_TOKEN=dev-mcp-token \
go run ./cmd/abs-mcp

Hermes や MCP Inspector などのローカルツールを含む Streamable HTTP クライアントでは、http://127.0.0.1:3333/mcp を指定します。ABS_HTTP_BEARER_TOKEN が設定されている場合は、一致するベアラートークンを送信するようクライアントを設定してください。このエンドポイントは OAuth ではなく静的なベアラートークンを使用します。OAuth 認可フローが後にサーバーへ導入された場合に限り、OAuth 保護リソースのメタデータをデプロイしてください。

クライアント設定

Claude Desktop、Cursor、VS Code、Windsurf はいずれも、コマンド、引数、環境変数を指定する stdio MCP サーバーに対応しています。絶対パスのバイナリを使用し、シークレットには env または --env-file を使用してください。

Claude Desktop の claude_desktop_config.json：

{
  "mcpServers": {
    "Audiobookshelf": {
      "command": "/path/to/abs-mcp",
      "args": [
        "--env-file",
        "/path/to/abs-mcp.env",
        "--extra-headers-file",
        "/path/to/cf-headers.json"
      ]
    }
  }
}

Claude Code：

claude mcp add Audiobookshelf /path/to/abs-mcp \
  -e ABS_BASE_URL=http://localhost:13378 \
  -e ABS_API_KEY=... \
  -e ABS_READ_ONLY=true

Cursor の mcp.json：

{
  "mcpServers": {
    "Audiobookshelf": {
      "command": "/path/to/abs-mcp",
      "env": {
        "ABS_BASE_URL": "http://localhost:13378",
        "ABS_API_KEY": "...",
        "ABS_READ_ONLY": "true"
      }
    }
  }
}

VS Code の MCP 設定：

{
  "servers": {
    "Audiobookshelf": {
      "type": "stdio",
      "command": "/path/to/abs-mcp",
      "env": {
        "ABS_BASE_URL": "http://localhost:13378",
        "ABS_API_KEY": "...",
        "ABS_READ_ONLY": "true"
      }
    }
  }
}

環境ファイルを使用する Windsurf の MCP 設定：

{
  "mcpServers": {
    "Audiobookshelf": {
      "command": "/path/to/abs-mcp",
      "args": [
        "--env-file",
        "/path/to/abs-mcp.env"
      ]
    }
  }
}

Docker ベースの stdio 設定：

{
  "mcpServers": {
    "Audiobookshelf": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "ABS_BASE_URL=http://host.docker.internal:13378",
        "-e",
        "ABS_API_KEY",
        "-e",
        "ABS_READ_ONLY=true",
        "ghcr.io/jeeftor/abs-mcp:0.5.0"
      ],
      "env": {
        "ABS_API_KEY": "..."
      }
    }
  }
}

コンテナイメージを直接実行します：

docker run --rm -i \
  -e ABS_BASE_URL=http://host.docker.internal:13388 \
  -e ABS_API_KEY=... \
  -e ABS_READ_ONLY=true \
  ghcr.io/jeeftor/abs-mcp:0.5.0

Cloudflare Access ヘッダーと、企業またはプライベート CA バンドルを使用する場合：

docker run --rm -i \
  -e ABS_BASE_URL=https://abs.example.com \
  -e ABS_API_KEY=... \
  -e ABS_EXTRA_HEADERS_FILE=/run/secrets/abs-headers.json \
  -e ABS_TLS_CA_CERT_FILE=/run/secrets/corporate-ca.pem \
  -v /path/to/headers.json:/run/secrets/abs-headers.json:ro \
  -v /path/to/corporate-ca.pem:/run/secrets/corporate-ca.pem:ro \
  ghcr.io/jeeftor/abs-mcp:0.5.0

ローカルイメージをビルドします：

make docker-build

ローカル開発

リポジトリ内の Audiobookshelf フィクスチャを起動し、ステージング済みのテストメディアをスキャンして、MCP サーバーをビルドし、ローカル MCP クライアント設定を書き込みます。

make dev

このターゲットを実行すると、Audiobookshelf が http://localhost:13388 で起動したままになり、.mcp.dev.json が書き込まれます。生成される設定は bin/abs-mcp を指定し、test/abs/.env.testing のフィクスチャトークンを含み、ABS_READ_ONLY=true を設定します。このファイルは Git の追跡対象外です。

ローカルクライアントで変更を伴うスキャンツールを有効にする必要がある場合は、このコマンドを使用します。

make mcp-dev-config-read-write

完了したらフィクスチャを停止します。

make abs-dev-down

ローカルの pre-commit フックをインストールします。

prek install
prek install --hook-type commit-msg

すべてのフックを手動で実行します。

prek run --all-files

テスト

ユニットテストとプロトコルテストを実行します。

make test-unit

Docker を使用した Audiobookshelf 統合テストを実行します。

make abs-test-integration

統合テストのターゲットは、テストの実行前にリポジトリ内の ABS フィクスチャをリセットしてスキャンします。

完了したらフィクスチャのコンテナを停止します。

make abs-dev-down

CI とリリース

GitHub Actions は、master へのプッシュとプルリクエストで、ユニットテスト、Go パッケージのテスト、バイナリのビルド、Docker イメージのビルドを実行します。

v* に一致するタグでは、amd64 および arm64 向けに Linux、macOS、Windows のリリースアーカイブを公開します。リリースワークフローでは、マルチアーキテクチャの Docker イメージも ghcr.io/jeeftor/abs-mcp に公開します。

MCP レジストリ

このリポジトリは、次の OCI パッケージパスを使用する公式 MCP レジストリに対応しています。

• レジストリ名：io.github.jeeftor/abs-mcp
• パッケージ：ghcr.io/jeeftor/abs-mcp:<version>
• レジストリトランスポート：stdio
• ランタイムトランスポート：デフォルトは stdio。オプションでローカルの Streamable HTTP を使用でき、ABS_TRANSPORT=http で設定します。
• メタデータファイル：server.json

Docker イメージには、必須の MCP 所有権ラベル io.modelcontextprotocol.server.name=io.github.jeeftor/abs-mcp が含まれています。

v* タグでは、リリースワークフローが不変の GHCR イメージタグをビルドし、server.json をタグのバージョンに書き換え、GitHub OIDC で MCP レジストリに認証して、mcp-publisher で公開します。GitHub OIDC には専用のレジストリシークレットは不要です。

公式レジストリへの登録が公開されると、下流のアグリゲーターがレジストリ API から情報を取得できるようになります。次に掲載先として検討するのが現実的なのは Glama です。Smithery への掲載は、このプロジェクトが stdio 配布用の MCPB バンドルを提供するか、外部認証を文書化した堅牢な公開 Streamable HTTP デプロイプロファイルを整備するまで待つ必要があります。