Audiobookshelf MCP

音频书架MCP服务器

模型上下文协议（MCP）服务器，提供与您的 有声书架 例子通过支持MCP的AI助手访问您的库、有声读物、播客、作者、收藏和播放列表。

免责声明

使用风险自负： 本软件按“原样”提供，不提供任何形式的保修。作者不对使用本软件可能引起的任何误用、事故、数据丢失或任何其他问题负责。用户全权负责确保在其Audiobookside实例中正确配置和使用此工具。

______________________________________________________________________

特性

• 列出并检索带有可选子资源（项目、作者）的库
• 获取个人项目（有声读物或播客）
• 浏览作者及其作品
• 访问收藏和播放列表
• 检索用户信息

安装

先决条件

• 具有API访问权限的Audiodsheffold实例
• 来自Audiobshelf实例的API令牌

推荐：下载预构建版本

最简单的安装方法是从 最新版本.

安装步骤：

1. 从发布页面下载适合您平台的存档
2. 提取存档：

   tar -xzf audiobookshelf-mcp_VERSION_PLATFORM.tar.gz

1. 将二进制文件移动到PATH中的某个位置（可选但推荐）：

   # macOS/Linux
   sudo mv abs-mcp /usr/local/bin/

   # Or to a user directory
   mv abs-mcp ~/.local/bin/

1. 使其可执行（macOS/Linux）：

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

替代方案：从源代码构建

如果您更喜欢从源代码构建：

先决条件：

• 转到1.21或更高版本

git clone 
cd abs-mcp
go build

配置

MCP服务器需要两个配置：

1. ABS_BASE_URL -您的Audio书架实例的基本URL（例如。， https://abs.example.com)
2. 防抱死制动系统_API_KEY -您的Audiobshelf API代币

获取您的API代币

1. 登录到您的Audio书架实例
2. 前往设置→ 用户→ 用户
3. 点击“生成API代币”或复制您现有的代币

用法

环境变量

您可以使用环境变量设置配置：

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

或者，您可以在调用工具时将这些作为参数传递（请参阅下面的工具参数）。

与Witsy建立联系

机智 是一款支持MCP服务器的桌面AI助手。以下是如何设置它：

1. 打开Witsy并转到设置(⚙️ 图标）
2. 导航到MCP部分
3. 添加具有以下配置的新服务器：

Witsy MCP Configuration

配置详细信息：

• 类型: 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代币）

1. 点击“保存”添加服务器
2. 服务器现在将在您的Witsy对话中可用！

使用Claude Desktop进行设置

将此添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %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"
      }
    }
  }
}

可用工具

图书馆

• 图书馆 -列出所有库
• 图书馆 -按ID获取单个库，或获取特定库的子资源：

- items=true -获取库中的所有项目 - authors=true -获取库中的所有作者 - series=true -获取库中的所有系列 - collections=true -获取图书馆的所有馆藏 - playlists=true -获取库中的所有播放列表 - personalized=true -获取图书馆的个性化视图 - filterdata=true -获取库的筛选数据 - stats=true -获取库统计信息 - episode-downloads=true -获取库的剧集下载 - recent-episodes=true -获取图书馆的最新剧集

• 创建库 -创建新库

- 必修的： name, folders （逗号分隔的路径）， media_type （书籍或播客） - 可选： icon, provider

物品

• 项目 -按ID获取单个项目（有声读物或播客），或获取特定项目子资源：

- cover=true -获取物品的封面图片 - tone-object=true -获取项目的音调对象

作者

• 作者 -按ID获取单个作者

集合

• 收藏 -列出所有收藏
• 收集 -按ID获取单个集合
• 创建集合 -创建新收藏

- 必修的： library_id, name - 可选： description

• add_to_collection -将书籍添加到现有收藏中

- 必修的： collection_id, book_id

播放列表

• 音乐播放清单 -列出所有播放列表
• 播放列表 -按ID获取单个播放列表
• 创建播放列表 -创建新的播放列表

- 必修的： library_id, name - 可选： description

• add_to_playlist -将项目添加到现有播放列表

- 必修的： playlist_id, item_id - 可选： episode_id （适用于播客剧集）

用户

• 我 -获取经过身份验证的用户信息，或获取特定的用户子资源：

- listening-sessions=true -为用户获取听力会话 - listening-stats=true -获取用户的收听统计数据 - items-in-progress=true -获取用户当前正在处理的项目 - progress_item_id= -获取特定库项目的进度 - progress_item_id= + progress_episode_id= -获取特定剧集的进度

会话

• 会话 -列出所有播放会话
• 会话 -按ID获取单个播放会话

播客

• 播客 -列出所有播客，或获取播客相关资源：

- feed=true -获取播客RSS订阅源 - opml=true -获取播客OPML导出

• 播客 -按ID获取单个播客，或获取播客子资源：

- downloads=true -获取播客的下载 - search-episode=true -在播客中搜索剧集 - episode_id= -按ID获取特定剧集

• check_podcast_episodes -检查播客的新剧集

- 必修的： podcast_id

进度跟踪

• update_progress -更新媒体项目的收听进度

- 必修的： item_id, progress （秒） - 可选： duration （以秒为单位）， is_finished （布尔值）， episode_id （适用于播客）

备份

• 创建备份 -创建服务器备份

刀具参数

所有工具均接受可选 base_url 和 token 覆盖环境变量的参数：

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

如果您需要访问多个Audioshelf实例或不想使用环境变量，这很有用。

查询示例

配置后，您可以向AI助手提出以下问题：

阅读和浏览：

• “显示我的所有有声读物库”
• “我的小说库里有什么项目？”
• “获取ID为abc123的作者的详细信息”
• “列出我的所有播放列表”
• “我目前正在阅读的收藏中有什么？”

创建和管理：

• “在我的图书馆创建一个名为‘夏日读物’的新收藏”
• “将这本书添加到我的“当前阅读”收藏中”
• “为我最喜欢的科幻有声读物创建一个新的播放列表”
• “检查新播客集”
• “将我在这本有声读物上的进度更新为45分钟”
• “创建我的服务器的备份”

AI助手将使用适当的MCP工具来获取信息并管理您的Audiobookstand实例。

发展

项目结构

• main.go -主服务器实现
• API身份验证和请求处理的助手函数
• MCP工具定义和处理程序

添加新工具

要添加新工具，请执行以下操作：

1. 使用定义工具选项 mcp.NewTool()
2. 添加身份验证参数 withABSAuth()
3. 向注册工具 s.AddTool()
4. 使用辅助函数，如 createSimpleGETHandler() 或 createGETByIDHandler()

许可证

GNU通用公共

贡献

欢迎投稿！请打开问题或提交拉取请求。

支持

关于以下问题：

• 此MCP服务器：在此存储库中打开问题
• 音频书架：参观 audiobookshelf.org
• MCP协议：见 模型上下文协议.io