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。