arr-mcp

别人每个服务都提供一个 MCP 服务，而这是专为整个媒体栈打造的 MCP 服务。

这正是它的意义所在，因为真正有意思的问题都发生在服务之间：

“我周二请求的电影为什么没有出现在 Jellyfin 中？”

没有任何一个服务能单独回答这个问题。它涉及 Seerr、Radarr、Prowlarr、SABnzbd 和 Jellyfin——五个 API、五套 ID、五个不完整的答案。arr-mcp 会将它们关联起来， 并给出因果链：

diagnose { query: "Blade" }

磁盘上还没有文件。请在 Radarr 或 Sonarr 中触发搜索——当前没有内容正在 下载，也没有索引器报告故障。

一次调用，一个答案。即使有服务离线，它也能作答，并会告诉你哪些部分无法检查，而不是对无法检查的部分妄加猜测。

为什么大家会用它

🔍 diagnose 能回答任何单个服务都回答不了的问题	遍历整条链路——已请求、已管理、已监控、已下载、已索引、已导入、已扫描——并指出最先能解释内容为何缺失的环节。
🧮 揭示质量配置文件无法实现其承诺的情况	无法达到的最低分数、偏好但从不强制要求的语言、按格式评分而其范围更广的同类格式却得分为零的情况。对于可通过算术验证的问题，我们会给出证明而非猜测；每项修复都会指出应在 Profilarr 中进行的具体更改，因为这些配置由它管理。
🛡️ 索引器文本只作为数据，绝不作为指令	来自公共索引器的发布名称可能受攻击者控制，并会直接流入模型上下文。arr-mcp 会对每一条此类文本进行隔离。
✋ 写入操作默认关闭、可预览且会记录	每个服务的写入操作默认关闭，需手动启用。每次写入都会准确展示将执行的操作，并等待确认——无论如何都会记录到审计日志中。
🖥️ 能诊断问题的配置页面	通过浏览器添加服务，查看出了什么问题以及该怎么处理，读取日志和写入审计记录。无需 YAML。
📚 三十九个工具，一套通用术语	所有列表都采用相同的分页方式；无论客户端是否读取 structuredContent，回复都清晰易读；每个错误都会指出可用于修复的配置键；每次写入都使用 ID，而不是标题。

在这个领域，其他产品完全没有做到最后五项。

快速开始 — 约两分钟

仓库中也提供了 docker-compose.example.yml。 在 Unraid 上，改用 unraid/arr-mcp.xml——这是一个 Community Applications 模板，已设置好 appdata 路径和 99:100 所有权。目前它尚未列入 CA，因此暂时请将其放入 /boot/config/plugins/dockerMan/templates-user/，然后在 Add Container 下的模板列表中选中它。启动后，下面的步骤 1 到 3 相同。

在 Proxmox VE 上，proxmox/ 会从源代码构建一个非特权 Debian LXC，而不是使用 Docker。请在主机上运行，不要在虚拟机中运行：

bash -c "$(curl -fsSL https://raw.githubusercontent.com/bardesss/arr-mcp/main/proxmox/ct/arr-mcp.sh)"

默认配置为 2 个核心、2 GB 内存和 8 GB 磁盘——内存是为可选的 IMDb 导入配置的，而非用于服务。config.yaml、MCP 令牌（经过哈希处理）和数据库都位于 /config 中，更新不会触碰这些内容；在容器内运行 update，即可从最新版本重新构建。在主机上再次运行上面的命令会创建第二个容器。如果安装成功却始终没有响应，请查看日志 journalctl -u arr-mcp。

它遵循 Community Scripts 的约定，但未列入其目录中，也从未在真实主机上运行过——尤其是 arm64，因此脚本会先询问，而不是自行假定。无论安装成功与否，我们都希望听到反馈： #265。启动后，下面的步骤 1 到 3 相同。

services:
  arr-mcp:
    image: ghcr.io/bardesss/arr-mcp:latest
    container_name: arr-mcp
    ports:
      - 6060:6060
    volumes:
      - ./config:/config
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Amsterdam
    restart: unless-stopped

1. 打开 http://<host>:6060——直接访问主机，不带路径。无需从容器日志中查找信息。

2. 认领实例。 首个页面是设置表单，而非登录页面：选择用户名和至少 12 个字符的密码。

重要

请在开放端口之前完成此操作。在实例被认领前，第一个打开该页面的人就会拥有此实例——而实例保存着每项服务的 API 密钥。

3. 添加服务——点击 Add a service，粘贴服务 URL 和 API 密钥（对于 Plex，使用其 X-Plex-Token；对于 Transmission 和 qBittorrent，使用用户名和密码），然后保存。设置会立即生效，无需重启。只配置你实际运行的服务。现在，即使配置文件无法解析，也不会再导致容器停止运行：arr-mcp 会显示包含错误信息和编辑器的修复页面。

你的 MCP 客户端通过 MCP 令牌访问 http://<host>:6060/mcp。在配置页面创建令牌；它只会显示一次，请立即复制到客户端中。每个令牌都有自己的级别和有效期，详见 MCP 令牌。如果客户端只能填写 URL、无法设置请求头，也可以通过 ?token= 携带令牌——详见 allow_token_in_url。如果你已经在运行身份提供方，/mcp 也接受短期 OAuth 2.1 访问令牌，因此每个客户端都能获得各自的凭证和权限范围，以限制其可执行的操作——一个客户端只读，另一个可以写入，但权限始终不会超出 config.yaml 已允许的范围。详见 auth.oauth。界面执行的所有操作最终都只涉及 config.yaml，仍然支持手动编辑。读取 MCP 注册表 的客户端可以在其中找到它，标识为 io.github.bardesss/arr-mcp。

可与任何指向它的客户端配合使用。 请求 Accept: application/json 的客户端（或完全不发送 Accept 的客户端）会收到一个带有 Content-Length 的 JSON 对象，而不会因为没有同时指定 text/event-stream 而遭到拒绝。接受流式响应的客户端仍会收到流。即使请求被拒绝，响应也会是 JSON。因此，普通的 curl 无需额外配置即可使用，完整的 MCP 客户端也同样可以。

镜像标签包括 X.Y.Z、X.Y、X 和 latest，以及用于尝鲜最新功能的 main。如果你希望自行审核每次新增的工具功能，可以固定使用一个次版本——例如 :1.6。镜像支持 amd64 和 arm64，因此 Raspberry Pi 或 ARM NAS 运行的构建与其他设备相同。

你可以这样提问

共有 38 个工具，但你无需说出它们的名称——只管提问，由模型来选择：

“现在正在下载什么？有没有卡住的？” “本周播出了哪些我还没看过的内容？” “我的哪些索引器出了问题？它们提示了什么？” “帮我找一部 1994 年出品、评分很高而且我还没有的影片。” “帮我给刚刚入库的电影找荷兰语字幕。” “不要那个版本——改下 1080p remux 版本。” “这一集为什么总是失败，也一直无法下载？” “暂停 SABnzbd，我需要用一小时带宽。” “我的做种规则是什么？现在还有内容超出规则限制仍在做种吗？” “那个下载几天前就完成了，却一直没导入——处理一下。” “将这部剧集设为 4K 配置文件，并且只监控未来的季。” “这个配置文件说要荷兰语，却一直下载英语版本——为什么？” “Radarr 中有没有内容偏离 Profilarr 的设置？” “我的哪些剧集的元数据与文件不匹配？” “这些剧集标题和文件不符——修正一下。” “取消监控第 5 季并删除它的文件。” ——始终先预览。

文档

工具	全部 39 个工具、每个工具能回答什么，以及含义不明显的字段
写入操作	如何启用写入操作、两个级别，以及预览并确认的流程
配置	config.yaml、需要使用列表的 7 个服务、Jellyfin 的 default_user，以及如何同时运行 Plex 和 Jellyfin
配置界面	4 个页面，以及每个页面不那么显而易见的功能
管理 API	供配套应用查看和管理服务、设置及令牌的 JSON API，使用在配置页面生成的密钥
IMDb 评分	获取剧集 IMDb 评分的唯一方法，以及相关费用
安全	针对 OWASP MCP Top 10 逐项说明威胁模型，包括无法解决的问题
贡献指南	符合条件的服务、如何添加适配器，以及 AI Agent 经常违反的规则

要求

• 至少有一项受支持且可通过局域网访问的服务：Radarr 4.0+、Sonarr 4.0+、 Whisparr 2.x（仅限 V2，不包括 Eros）、Prowlarr 1.0+、Bazarr 1.4+、Jellyfin 10.9+、Plex Media Server 1.32+、 Seerr 1.0+、SABnzbd 3.0+、Transmission 3.0+、qBittorrent 4.1+、Profilarr 2.2.0+
• Docker，或者 Node 24+，用于从源代码运行
• 使用协议修订版本 2026-07-28 的 MCP 客户端

自 1.0 起，工具接口就是公共 API：重命名或移除工具、参数或响应字段都属于重大变更，因为这种破坏是无声的——模型会找不到改名后的工具，而不会报错。

贡献

欢迎贡献，尤其欢迎新增服务适配器——目前我们会接受 Lidarr、Emby 和 Deluge 的适配器，列表中已提前说明，也列出了不会接受的适配器。适配器是代码库中刻意设计得最为独立的部分。请先了解两点：并非所有服务都符合要求，而且标准已明确写出，不会针对每个拉取请求单独决定——符合要求的服务。另外，我无法测试自己没有运行的服务，因此第二条标准是：你已在自己的实际实例上进行测试，并在 PR 中说明测试内容和对应的版本。

还有一个适配器尚未验证：qBittorrent。 维护者既没有运行 Plex，也没有运行 qBittorrent——测试意味着在你自己的服务器上运行构建，并报告测试结果。Plex 后来已由两位志愿测试者在两台实际运行的 Plex Media Server 上完成验证，其中包括首次写入；此后，它的元数据修复功能也已在实际服务器上成功修复电影和剧集（#312）；qBittorrent 已发布，但仍在等待同类测试报告。Plex 背后的设计，以及其他待处理项目。

欢迎使用 AI 辅助贡献，但标准不变，也没有其他额外要求；arr-mcp 本身就是借助编码 Agent 构建的。请让你的 Agent 参考CONTRIBUTING.md。

缺少某个工具？ 请提交问题，描述你无法获得答案的问题，而不是你认为应该存在的工具。很多时候，只需为现有工具新增参数即可；如果确实需要新工具，你提出的问题就能帮助我们判断。

安全

arr-mcp 并非为暴露到互联网而设计。/mcp 端点需要持有者令牌，因为“仅限局域网”只是一种网络假设，并非安全控制——该端点连接着你配置的所有服务凭据，启用后还涉及文件删除，而家庭网络中也有访客手机和物联网设备。如果需要让它离开局域网，请将其置于带 TLS 的反向代理之后，并设置 allowed_hosts。

网络之外：写入功能默认关闭，启用后每次写入都会先预览并确认，然后才会执行；服务返回的所有内容都会被限定为数据，而非指令。安全 逐项对照 OWASP MCP Top 10 进行说明，也明确指出了它无法解决的问题。发现问题？请参阅 SECURITY.md。

致谢

arr-mcp 是粘合层；困难的部分都归功于其他人。它对接的几乎所有服务都是主要由志愿者维护的免费软件——Radarr、Sonarr、Whisparr、Prowlarr、Bazarr、Jellyfin、Seerr、SABnzbd、Transmission、qBittorrent、Profilarr——它所基于的库也同样如此：MCP TypeScript SDK、Hono、Zod、Pino、Vitest、yaml 和 TypeScript。如果你觉得 arr-mcp 有用，不妨优先支持这些项目。Plex 是个例外：它是商业产品，但其 API 承担的工作量不亚于其他服务。

启用 IMDb 数据集 时：相关信息由 IMDb 提供，经许可用于个人及非商业用途。

许可

MIT