Audiobookshelf MCP

🚀 オーディオブックシェルフMCPサーバー

オーディオブックシェルフ インスタンスとやり取りするためのツールを提供するモデルコンテキストプロトコル（MCP）サーバーです。MCPをサポートするAIアシスタントを通じて、ライブラリ、オーディオブック、ポッドキャスト、著者、コレクション、プレイリストにアクセスできます。

免責事項

自己責任で使用してください：このソフトウェアは「現状のまま」提供され、いかなる保証もありません。著者は、このソフトウェアの使用によって生じる誤用、事故、データ損失、またはその他の問題について一切責任を負いません。ユーザーは、このツールをオーディオブックシェルフインスタンスと適切に構成して使用する責任を負います。

✨ 主な機能

• オプションのサブリソース（アイテム、著者）を含むライブラリを一覧表示および取得
• 個々のアイテム（オーディオブックまたはポッドキャスト）を取得
• 著者とその作品を閲覧
• コレクションとプレイリストにアクセス
• ユーザー情報を取得

📦 インストール

前提条件

• APIアクセス可能なオーディオブックシェルフインスタンス
• オーディオブックシェルフインスタンスから取得したAPIトークン

推奨：事前ビルド版をダウンロード

最も簡単なインストール方法は、最新リリースから事前ビルド済みのバイナリをダウンロードすることです。

インストール手順：

1. リリースページから、あなたのプラットフォームに適したアーカイブをダウンロードします。
2. アーカイブを解凍します：

   tar -xzf audiobookshelf-mcp_VERSION_PLATFORM.tar.gz
   

3. バイナリをPATH内の場所に移動します（オプションですが推奨）：

   # macOS/Linux
   sudo mv abs-mcp /usr/local/bin/
   
   # またはユーザーディレクトリに移動
   mv abs-mcp ~/.local/bin/
   

4. 実行可能にします（macOS/Linux）：

   chmod +x /usr/local/bin/abs-mcp
   

代替方法：ソースからビルド

ソースからビルドする場合は、以下の前提条件が必要です。

• Go 1.21 以上

git clone <repository-url>
cd abs-mcp
go build

設定

MCPサーバーには2つの設定が必要です。

1. ABS_BASE_URL - オーディオブックシェルフインスタンスのベースURL（例：https://abs.example.com）
2. ABS_API_KEY - オーディオブックシェルフのAPIトークン

APIトークンの取得方法

1. オーディオブックシェルフインスタンスにログインします。
2. 設定 → ユーザー → あなたのユーザーに移動します。
3. 「APIトークンを生成」をクリックするか、既存のトークンをコピーします。

💻 使用例

環境変数

環境変数を使用して設定を行うことができます。

export ABS_BASE_URL="https://abs.example.com"
export ABS_API_KEY="your-api-token-here"

あるいは、ツールを呼び出す際にこれらをパラメータとして渡すこともできます（以下のツールパラメータを参照）。

Witsyでの設定

Witsy は、MCPサーバーをサポートするデスクトップAIアシスタントです。以下は設定方法です。

1. Witsyを開き、設定（⚙️ アイコン）に移動します。
2. MCPセクションに移動します。
3. 次の設定で新しいサーバーを追加します。

設定詳細：

• タイプ：stdio
• ラベル：abs-mcp（または好きな名前）
• コマンド：/path/to/abs-mcp（「選択」ボタンを使用してコンパイル済みのバイナリを選択）
• 引数：（空白）
• 作業ディレクトリ：任意のディレクトリ（例：/Users/yourname/Downloads）
• 環境変数：
  • ABS_BASE_URL = https://example.library.abs（オーディオブックシェルフのURL）
  • ABS_API_KEY = IM_A_LONG_STRING（APIトークン）

4. 「保存」をクリックしてサーバーを追加します。
5. サーバーは、Witsyの会話で使用できるようになります！

利用可能なツール

ライブラリ

• libraries - すべてのライブラリを一覧表示
• library - IDで単一のライブラリを取得するか、特定のライブラリサブリソースを取得します。
  • items=true - ライブラリ内のすべてのアイテムを取得
  • authors=true - ライブラリ内のすべての著者を取得
  • series=true - ライブラリ内のすべてのシリーズを取得
  • collections=true - ライブラリ内のすべてのコレクションを取得
  • playlists=true - ライブラリ内のすべてのプレイリストを取得
  • personalized=true - ライブラリのパーソナライズされたビューを取得
  • filterdata=true - ライブラリのフィルターデータを取得
  • stats=true - ライブラリの統計情報を取得
  • episode-downloads=true - ライブラリのエピソードダウンロードを取得
  • recent-episodes=true - ライブラリの最近のエピソードを取得
• create_library - 新しいライブラリを作成
  • 必須：name、folders（カンマ区切りのパス）、media_type（bookまたはpodcast）
  • オプション：icon、provider

アイテム

• item - IDで単一のアイテム（オーディオブックまたはポッドキャスト）を取得するか、特定のアイテムサブリソースを取得します。
  • cover=true - アイテムの表紙画像を取得
  • tone-object=true - アイテムのトーンオブジェクトを取得

著者

• author - IDで単一の著者を取得

コレクション

• collections - すべてのコレクションを一覧表示
• collection - IDで単一のコレクションを取得
• create_collection - 新しいコレクションを作成
  • 必須：library_id、name
  • オプション：description
• add_to_collection - 既存のコレクションに本を追加
  • 必須：collection_id、book_id

プレイリスト

• playlists - すべてのプレイリストを一覧表示
• playlist - IDで単一のプレイリストを取得
• create_playlist - 新しいプレイリストを作成
  • 必須：library_id、name
  • オプション：description
• add_to_playlist - 既存のプレイリストにアイテムを追加
  • 必須：playlist_id、item_id
  • オプション：episode_id（ポッドキャストエピソードの場合）

ユーザー

• me - 認証されたユーザー情報を取得するか、特定のユーザーサブリソースを取得します。
  • listening-sessions=true - ユーザーの聴取セッションを取得
  • listening-stats=true - ユーザーの聴取統計情報を取得
  • items-in-progress=true - ユーザーが現在読んでいるアイテムを取得
  • progress_item_id=<id> - 特定のライブラリアイテムの進捗状況を取得
  • progress_item_id=<id> + progress_episode_id=<id> - 特定のエピソードの進捗状況を取得

セッション

• sessions - すべての再生セッションを一覧表示
• session - IDで単一の再生セッションを取得

ポッドキャスト

• podcasts - すべてのポッドキャストを一覧表示するか、ポッドキャスト関連のリソースを取得します。
  • feed=true - ポッドキャストのRSSフィードを取得
  • opml=true - ポッドキャストのOPMLエクスポートを取得
• podcast - IDで単一のポッドキャストを取得するか、ポッドキャストサブリソースを取得します。
  • downloads=true - ポッドキャストのダウンロードを取得
  • search-episode=true - ポッドキャスト内のエピソードを検索
  • episode_id=<id> - IDで特定のエピソードを取得
• check_podcast_episodes - ポッドキャストの新しいエピソードを確認
  • 必須：podcast_id

進捗追跡

• update_progress - メディアアイテムの聴取進捗を更新
  • 必須：item_id、progress（秒単位）
  • オプション：duration（秒単位）、is_finished（ブール値）、episode_id（ポッドキャストの場合）

バックアップ

• create_backup - サーバーのバックアップを作成

ツールパラメータ

すべてのツールは、環境変数を上書きするオプションのbase_urlとtokenパラメータを受け付けます。

{
  "base_url": "https://abs.example.com",
  "token": "your-api-token-here"
}

これは、複数のオーディオブックシェルフインスタンスにアクセスする必要がある場合や、環境変数を使用したくない場合に便利です。

クエリ例

設定が完了すると、AIアシスタントに次のような質問をすることができます。

閲覧とブラウジング：

• 「すべてのオーディオブックライブラリを表示して」
• 「私のフィクションライブラリにはどんなアイテムがありますか？」
• 「IDがabc123の著者の詳細を取得して」
• 「すべてのプレイリストを一覧表示して」
• 「私の現在読んでいるコレクションには何が入っていますか？」

作成と管理：

• 「私のライブラリに 'Summer Reads' という名前の新しいコレクションを作成して」
• 「この本を私の '現在読んでいる' コレクションに追加して」
• 「私のお気に入りのサイエンスフィクションオーディオブック用の新しいプレイリストを作成して」
• 「新しいポッドキャストエピソードを確認して」
• 「このオーディオブックの進捗を45分に更新して」
• 「サーバーのバックアップを作成して」

AIアシスタントは、適切なMCPツールを使用して情報を取得し、オーディオブックシェルフインスタンスを管理します。

開発

プロジェクト構造

• main.go - メインサーバーの実装
• API認証とリクエスト処理のヘルパー関数
• MCPツールの定義とハンドラー

新しいツールの追加

新しいツールを追加するには、以下の手順を実行します。

1. mcp.NewTool() を使用してツールオプションを定義します。
2. withABSAuth() で認証パラメータを追加します。
3. s.AddTool() でツールを登録します。
4. createSimpleGETHandler() または createGETByIDHandler() などのヘルパー関数を使用します。

📄 ライセンス

GNU General Public

コントリビューション

コントリビューションは大歓迎です！ 問題を開くか、プルリクエストを送信してください。

サポート

以下に関連する問題については：

• このMCPサーバー：このリポジトリで問題を開いてください。
• オーディオブックシェルフ：audiobookshelf.org を訪問してください。
• MCPプロトコル：modelcontextprotocol.io を参照してください。