金大哥 - audiobookshelf-mcp MCP 详情

article

README

🚀 Audiobookshelf MCP 服务器

Audiobookshelf MCP 服务器是一个基于模型上下文协议（MCP）的服务，它能让支持 MCP 的 AI 助手与你的 Audiobookshelf 实例进行交互。借助该服务器，你可以通过 AI 助手便捷地访问你的有声书库、播客、作者信息、合集以及播放列表等内容。

⚠️ 免责声明

使用风险自负：本软件按“原样”提供，不附带任何形式的保证。作者不对因使用本软件而可能产生的任何滥用、事故、数据丢失或其他问题负责。用户需自行确保该工具与他们的 Audiobookshelf 实例的正确配置和使用。

✨ 主要特性

列出并检索有声书库，还可选择获取子资源（如书籍、作者）。
获取单个书籍或播客的详细信息。
浏览作者及其作品。
访问合集和播放列表。
获取用户信息。

📦 安装指南

前提条件

拥有一个可通过 API 访问的 Audiobookshelf 实例。
从你的 Audiobookshelf 实例获取 API 令牌。

推荐方式：下载预构建版本

最简单的安装方式是从最新版本下载预构建的二进制文件。

| 平台 | 架构 | 文件名 | |------|------|--------| | macOS | Intel (x86_64) | audiobookshelf-mcp_VERSION_darwin_amd64.tar.gz | | macOS | Apple Silicon (ARM64) | audiobookshelf-mcp_VERSION_darwin_arm64.tar.gz | | Linux | 64 位 (x86_64) | audiobookshelf-mcp_VERSION_linux_amd64.tar.gz | | Linux | ARM64 | audiobookshelf-mcp_VERSION_linux_arm64.tar.gz | | Linux | 32 位 (x86) | audiobookshelf-mcp_VERSION_linux_386.tar.gz | | Windows | 64 位 (x86_64) | audiobookshelf-mcp_VERSION_windows_amd64.tar.gz | | Windows | ARM64 | audiobookshelf-mcp_VERSION_windows_arm64.tar.gz | | Windows | 32 位 (x86) | audiobookshelf-mcp_VERSION_windows_386.tar.gz |

安装步骤：

从发布页面下载适合你平台的压缩包。

解压压缩包：

tar -xzf audiobookshelf-mcp_VERSION_PLATFORM.tar.gz

将二进制文件移动到系统路径中（可选但推荐）：

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

# 或者移动到用户目录
mv abs-mcp ~/.local/bin/

使文件可执行（仅适用于 macOS/Linux）：
```
chmod +x /usr/local/bin/abs-mcp
```

替代方式：从源代码构建

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

前提条件：

Go 1.21 或更高版本。

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

🔧 配置说明

MCP 服务器需要两项配置：

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

获取 API 令牌

登录到你的 Audiobookshelf 实例。
进入设置 → 用户 → 你的用户。
点击“生成 API 令牌”或复制现有的令牌。

💻 使用示例

环境变量设置

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

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

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

与 Witsy 集成设置

Witsy 是一款支持 MCP 服务器的桌面 AI 助手。以下是设置步骤：

打开 Witsy 并进入设置（⚙️ 图标）。
导航到 MCP 部分。
添加一个新服务器，配置如下：

Witsy MCP 配置

配置详情：

类型：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 令牌）

点击“保存”以添加服务器。
现在，该服务器将在你的 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 工具定义和处理程序。

添加新工具

要添加新工具，请按以下步骤操作：

使用 mcp.NewTool() 定义工具选项。
使用 withABSAuth() 添加认证参数。
使用 s.AddTool() 注册工具。
使用 createSimpleGETHandler() 或 createGETByIDHandler() 等辅助函数。

📄 许可证

GNU 通用公共许可证。

🤝 贡献说明

欢迎贡献代码！请提交问题或拉取请求。

🛠️ 支持信息

如果你遇到以下相关问题：

此 MCP 服务器 - 请在此仓库中提交问题。
Audiobookshelf - 请访问 audiobookshelf.org。
MCP 协议 - 请参阅 modelcontextprotocol.io。

audiobookshelf-mcp