Audiobookshelf MCP

🚀 Audiobookshelf MCP 服務器

Audiobookshelf MCP 服務器是一個基於模型上下文協議（MCP）的服務，它能讓支持 MCP 的 AI 助手與你的 Audiobookshelf 實例進行交互。藉助該服務器，你可以通過 AI 助手便捷地訪問你的有聲書庫、播客、作者信息、合集以及播放列表等內容。

⚠️ 免責聲明

使用風險自負：本軟件按“原樣”提供，不附帶任何形式的保證。作者不對因使用本軟件而可能產生的任何濫用、事故、數據丟失或其他問題負責。用戶需自行確保該工具與他們的 Audiobookshelf 實例的正確配置和使用。

✨ 主要特性

• 列出並檢索有聲書庫，還可選擇獲取子資源（如書籍、作者）。
• 獲取單個書籍或播客的詳細信息。
• 瀏覽作者及其作品。
• 訪問合集和播放列表。
• 獲取用戶信息。

📦 安裝指南

前提條件

• 擁有一個可通過 API 訪問的 Audiobookshelf 實例。
• 從你的 Audiobookshelf 實例獲取 API 令牌。

推薦方式：下載預構建版本

最簡單的安裝方式是從 最新版本 下載預構建的二進制文件。

安裝步驟：

1. 從發佈頁面下載適合你平臺的壓縮包。
2. 解壓壓縮包：

   tar -xzf audiobookshelf-mcp_VERSION_PLATFORM.tar.gz
   

3. 將二進制文件移動到系統路徑中（可選但推薦）：

   # 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 服務器需要兩項配置：

1. ABS_BASE_URL - 你的 Audiobookshelf 實例的基礎 URL（例如：https://abs.example.com）。
2. ABS_API_KEY - 你的 Audiobookshelf API 令牌。

獲取 API 令牌

1. 登錄到你的 Audiobookshelf 實例。
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（你的 Audiobookshelf URL）
  • ABS_API_KEY = IM_A_LONG_STRING（你的 API 令牌）

4. 點擊“保存”以添加服務器。
5. 現在，該服務器將在你的 Witsy 對話中可用！

與 Claude Desktop 集成設置

將以下內容添加到你的 Claude Desktop 配置文件中： macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "audiobookshelf": {
      "command": "/path/to/abs-mcp",
      "env": {
        "ABS_BASE_URL": "https://abs.example.com",
        "ABS_API_KEY": "your-api-token-here"
      }
    }
  }
}

📚 詳細文檔

可用工具

有聲書庫相關

• 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（書籍或播客）。
  • 可選參數：icon（圖標），provider（提供者）。

書籍相關

• item - 通過 ID 獲取單個書籍或播客，或獲取特定的子資源：
  • cover=true - 獲取書籍的封面圖片。
  • tone-object=true - 獲取書籍的語氣對象。

作者相關

• author - 通過 ID 獲取單個作者。

合集相關

• collections - 列出所有合集。
• collection - 通過 ID 獲取單個合集。
• create_collection - 創建一個新的合集。
  • 必需參數：library_id（庫 ID），name（名稱）。
  • 可選參數：description（描述）。
• add_to_collection - 將一本書添加到現有的合集中。
  • 必需參數：collection_id（合集 ID），book_id（書籍 ID）。

播放列表相關

• playlists - 列出所有播放列表。
• playlist - 通過 ID 獲取單個播放列表。
• create_playlist - 創建一個新的播放列表。
  • 必需參數：library_id（庫 ID），name（名稱）。
  • 可選參數：description（描述）。
• add_to_playlist - 將一個項目添加到現有的播放列表中。
  • 必需參數：playlist_id（播放列表 ID），item_id（項目 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（播客 ID）。

進度跟蹤相關

• update_progress - 更新媒體項目的收聽進度。
  • 必需參數：item_id（項目 ID），progress（以秒為單位的進度）。
  • 可選參數：duration（以秒為單位的時長），is_finished（布爾值，表示是否完成），episode_id（僅適用於播客）。

備份相關

• create_backup - 創建服務器備份。

工具參數

所有工具都接受可選的 base_url 和 token 參數，這些參數將覆蓋環境變量：

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

如果你需要訪問多個 Audiobookshelf 實例或不想使用環境變量，這將非常有用。

示例查詢

配置完成後，你可以向你的 AI 助手提出以下問題：

閱讀和瀏覽：

• "顯示我所有的有聲書庫"
• "我的小說庫中有哪些書籍？"
• "獲取 ID 為 abc123 的作者的詳細信息"
• "列出我所有的播放列表"
• "我的'正在閱讀'合集中有哪些內容？"

創建和管理：

• "在我的庫中創建一個名為'夏日讀物'的新合集"
• "將這本書添加到我的'正在閱讀'合集中"
• "為我最喜歡的科幻有聲書創建一個新的播放列表"
• "檢查新的播客劇集"
• "將我在這本有聲書上的進度更新到 45 分鐘"
• "創建我的服務器備份"

AI 助手將使用相應的 MCP 工具來獲取信息並管理你的 Audiobookshelf 實例。

👨‍💻 開發指南

項目結構

• main.go - 主服務器實現。
• 用於 API 認證和請求處理的輔助函數。
• MCP 工具定義和處理程序。

添加新工具

要添加新工具，請按以下步驟操作：

1. 使用 mcp.NewTool() 定義工具選項。
2. 使用 withABSAuth() 添加認證參數。
3. 使用 s.AddTool() 註冊工具。
4. 使用 createSimpleGETHandler() 或 createGETByIDHandler() 等輔助函數。

📄 許可證

GNU 通用公共許可證。

🤝 貢獻說明

歡迎貢獻代碼！請提交問題或拉取請求。

🛠️ 支持信息

如果你遇到以下相關問題：

• 此 MCP 服務器 - 請在此倉庫中提交問題。
• Audiobookshelf - 請訪問 audiobookshelf.org。
• MCP 協議 - 請參閱 modelcontextprotocol.io。