用途
audiobookshelf-mcp 是一个 Model Context Protocol（MCP）服务器，用于连接 Audiobookshelf——自托管的有声书与播客服务器。它让 MCP 客户端（如 Claude Code、Claude Desktop、Codex）能够浏览媒体库、回答关于用户拥有什么、听过什么的问题，并保持收听进度、书签、收藏和播放列表同步。
主要能力
服务器共提供 44 个工具，其中 29 个只读、15 个可写。工具数量是上限而非下限：通过 AUDIOBOOKSHELF_ALLOW_TOOLS=essential 可只注册精选的 8 个工具（list_libraries、search_library、list_library_items、get_library_item、get_item_chapters、list_items_in_progress、get_media_progress、set_media_progress），模型从 8 个工具中选择通常比从 44 个中更可靠。
每个响应都是投影而非原始对象。展开的媒体库条目会携带每个音频文件、音轨和章节及完整 ffprobe 元数据，而媒体工具默认返回紧凑结构，需要原始对象时可传 detail="full"。
44 个工具中有 29 个只读。设置 AUDIOBOOKSHELF_READ_ONLY=true 后只注册这些只读工具，写入工具不会出现在 tools/list 中，而不是在调用时被拒绝。
六个会移除内容的工具会先询问真人，通过 MCP elicitation 弹出模型无法代为回答的对话框；在客户端无法显示对话框时，回退为绑定确切目标的一次性令牌。
使用方式
运行要求：Node.js 22 或更高版本；Audiobookshelf 2.26.0 或更高版本（更早版本没有 API 密钥）；一个 Audiobookshelf API 密钥。
获取 API 密钥：由管理员在 Settings → Users → API Keys 下管理。密钥代表恰好一个 Audiobookshelf 用户行事并继承该用户的权限，因此为普通账户签发的密钥看不到该账户看不到的媒体库，也不能删除该账户无权删除的内容。密钥仅在创建时显示一次。
服务器无需配置即可启动：它完成 MCP 握手并列出工具，之后每次调用都会失败并给出设置说明。这是有意为之，以便注册表和沙箱检查器能够内省它。
选择加载哪些工具：AUDIOBOOKSHELF_ALLOW_TOOLS 和 AUDIOBOOKSHELF_DENY_TOOLS 接受逗号分隔的工具名，末尾的 * 匹配整个工具族。essential 是精选的 8 个工具预设。匹配不到任何工具的条目会导致启动中止并指出该条目，因此拼写错误不会静默隐藏工具。被过滤的工具永远不会注册，因此在 tools/list 中不存在，tools/call 也不认识它，与 AUDIOBOOKSHELF_READ_ONLY 下的写入工具完全一样。
如果同时运行多个此类服务器，mcp-hub 是另一种方案——其 /hub 端点用六个元工具替换每个服务器的工具。
客户端配置示例（claude_desktop_config.json、~/.codex/config.toml 等）以及 Docker 运行方式（-i 必需，协议通过 stdin 和 stdout 运行，没有端口可发布）在客户端指南中有更多说明。
通过 mcp-hub：无法生成本地进程的客户端（ChatGPT connectors、Claude on the web、Cursor、LibreChat）可通过 mcp-hub 访问 audiobookshelf-mcp：一个容器通过 Streamable HTTP 服务多个 stdio MCP 服务器，使用单一密码后的 OAuth 2.1 登录，并为无法进行 OAuth 的客户端提供长期令牌。其 /hub 端点将所有服务器置于六个元工具之后，因此一个连接器即可访问所有服务器，而无需在模型上下文中放置 N×工具模式，并且它同时支持两个协议修订版。
适用场景
适用于希望用 MCP 客户端查询和管理自托管 Audiobookshelf 媒体库的用户，例如浏览媒体库、搜索内容、查看收听进度与统计、同步书签、收藏和播放列表。
限制
有意不暴露的功能：无播放功能（暂停、跳转、播放属于真实客户端的会话状态机；set_media_progress 覆盖“标记为已完成”和“跳转到第 12 章”，播放由手机完成）；无管理功能，即使使用管理员密钥也没有用户管理、服务器设置、备份、缓存清理、文件系统浏览、媒体库或条目删除、元数据重写或文件上传的工具。
安全设计：只读模式不注册写入工具；八个可能移除内容的工具（三个删除、delete_bookmark、remove_books_from_collection、remove_items_from_playlist，以及被要求重排时的 update_collection / update_playlist）通过 MCP elicitation 弹出真人对话框；确认提示从不引用 API 内容，只列出 id 和数量；返回 200 但非 JSON 视为错误；不受信任的内容会被标记；API 密钥在读取配置后从环境中删除；不跟随重定向，每个请求有 15 秒超时；id 在进入 URL 路径前经过验证；上游错误正文经过净化；进度更新只发送白名单字段。
来自 Audiobookshelf 本身的一个注意事项：从播放列表中移除最后一项会删除该播放列表，remove_items_from_playlist 在发生时会在结果中说明。
响应大小限制：5 MB 响应上限（读取前检查 content-length，分块正文在读取时计数）；100 000 字节结果上限（在 jsonResult 中应用，覆盖 detail="full"，整条丢弃而非截断字符）；嵌入成员上限（紧凑的收藏或播放列表嵌入前 25 本书或条目并报告真实数量，get_collection 和 get_playlist 返回其中一个的完整成员）。list_library_items 支持 limit 和 page 分页；七个列表工具没有分页参数，因为其背后的 Audiobookshelf 路由一次返回全部内容且不接受分页参数。
完整指南、工具参考和安全说明位于 audiobookshelf-mcp.ni-c.de（源码在 docs/ 中）。项目采用 MIT 许可证。
