Yarr MCP

yarr

通过 MCP 和 CLI，对 Sonarr、Radarr、Plex 及相关应用组成的媒体集群进行自托管运维。

如果你使用 Claude Code、Codex 或 Gemini CLI 管理自托管媒体技术栈，yarr 可为 Agent 提供一种统一的方式来查询和控制所有服务，而不必使用 11 种各不相同的临时集成。它是一个上游客户端 MCP 服务：不会取代这些应用，也不会将每个 REST 端点都镜像成 Web UI。它的作用是为 Agent 提供统一的工具界面，并为运维人员提供等效的 CLI 界面。

**不适用于：**作为面向任意服务的通用 REST 网关，或独立的调度／自动化引擎。yarr 只与其支持的服务类型交互，并且只会执行你或你的 Agent 要求的操作。

目录

• 命名
• 功能与边界
• 安装
• Unraid 插件
• 快速入门
• 客户端配置
• 运行时界面
• MCP 工具参考
• CLI 参考
• 配置
• 身份验证
• 安全与信任模型
• 架构
• 分发约定
• 开发
• 验证
• 部署
• 故障排除
• 相关服务
• 文档
• 许可证

命名

此代码库发布于 github.com/dinglebear-ai/yarr。

Rust 包和安装后的二进制文件都名为 yarr。npm 启动器包名为 yarr-mcp，因为较短的 yarr 名称已在 npm 上被占用；安装启动器后仍可使用 yarr 命令。MCP 注册表名称为 ai.dinglebear/yarr，Docker 镜像使用 ghcr.io/dinglebear-ai/yarr。生产环境的 Compose 部署通过不可变清单摘要选择该镜像。

插件的命名有意区分如下：

• yarr 是完整的 MCP 服务插件。它通过标准输入／输出启动与此代码库配套的 @dinglebear/yarr npm 包，并包含各服务的备用技能；不会提交特定平台的二进制文件。
• sonarr、radarr、prowlarr、overseerr、sabnzbd、qbittorrent、plex、jellyfin、tautulli、tracearr 和 bazarr 是仅包含技能的插件，不提供 MCP 服务，也不捆绑二进制文件。

功能与边界

yarr 通过一个按操作分发的服务层封装已配置的媒体自动化集群。MCP 和 CLI 调用由同一套实现提供支持，因此“Agent 使用工具”和“运维人员运行命令”不会出现行为偏差。

主要功能：

• 检查已配置服务的集群状态。
• 对已知服务类型提供带凭据的上游 API 直通访问。
• 为 Sonarr、Radarr、Prowlarr、Overseerr、Jellyfin 和 Plex 提供由表驱动的 OpenAPI 操作元数据。执行器遵循声明的参数、请求媒体类型和成功响应传输约定；不受支持的条目会被排除，并列在生成的功能矩阵中。
• 为 SABnzbd、qBittorrent、Tautulli、Bazarr 和 Tracearr 提供精选命令；这些服务的上游未提供可用的机器可读规范。
• 通过 MCP 使用 Code Mode 编写多步骤媒体自动化脚本。
• 存储并执行代码片段，以便重复运行 Code Mode 工作流。
• 为各个服务提供仅包含插件、通过直接 HTTP 访问的备用方案。

边界：

• yarr 不会自行存储或调度媒体任务。
• 它不提供本地 REST 操作 API 或内嵌 Web UI。
• 它不接受任意未知的服务类型。
• MCP 调用方绝不会将凭据、令牌、密钥或机密作为操作参数传入。凭据来自环境变量、配置文件，或严格限定的单服务插件 JSON 配置。

安装

原生版本安装程序是最安全的默认选择，因为它会在将 yarr 安装到 ~/.local/bin 之前验证版本归档和 SHA-256：

curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/yarr/main/install.sh | bash
yarr --version

npm 启动器是一种配套发行版，并非指向恰好被标记为 latest 的版本的别名。使用前，请确认 npm 上存在确切的版本：

YARR_VERSION=2.1.0
npm view "@dinglebear/yarr@${YARR_VERSION}" version
npx -y "@dinglebear/yarr@${YARR_VERSION}" mcp
# Or, after the same availability check:
npm i -g "@dinglebear/yarr@${YARR_VERSION}"

切勿在 MCP 清单中使用未固定版本的 npx @dinglebear/yarr 或 @latest：部分发布后，npm 可能仍指向较旧的启动器。在本文档更新时，GitHub 版本 v2.1.0 已公开发布，但 npm 上尚无 @dinglebear/[email protected]；相关恢复工作正在 issue #80 中跟踪。在确切的 npm 版本可用之前，请使用原生安装程序、经过验证的版本归档、源码构建，或独立的 Unraid 软件包。

Unraid 插件

协调发布的 Unraid 发行版位于 unraid-plugin/ 下。它整合了经典 .plg 安装程序和特权服务生命周期、外部 NestJS GraphQL 扩展，以及 Vue 设置／仪表板自定义元素。

在 Unraid 的 Plugins > Install Plugin 页面安装插件 URL：

https://raw.githubusercontent.com/dinglebear-ai/yarr/main/unraid-plugin/yarr.plg

全新安装会将 Yarr 绑定到环回地址。配置身份验证之前，系统会拒绝 LAN 或自定义地址绑定；Tailscale Serve 是受支持的仅限 tailnet 的选项。服务凭据保留在服务器端启动配置中，绝不会返回给浏览器。有关持久化、发现、更新、回滚、卸载后的保留行为、故障排查和发布门槛，请参阅 Unraid 操作员与发布指南。

快速入门

首次使用者的 30 秒入门流程如下：

export YARR_SERVICES=sonarr
export YARR_SONARR_URL=http://127.0.0.1:8989
export YARR_SONARR_API_KEY=...

yarr sonarr status
yarr mcp

然后，将 MCP 客户端指向 stdio 命令：

{
  "mcpServers": {
    "yarr": {
      "command": "yarr",
      "args": ["mcp"],
      "env": {
        "YARR_SERVICES": "sonarr",
        "YARR_SONARR_URL": "http://127.0.0.1:8989",
        "YARR_SONARR_API_KEY": "${YARR_SONARR_API_KEY}"
      }
    }
  }
}

安装 Claude Code 插件时，请在 Claude Code 聊天会话中使用市场命令，而不要在 shell 中运行：

/plugin marketplace add dinglebear-ai/yarr
/plugin install yarr@yarr

完整插件会启动其清单中固定的确切版本。安装或调试插件前，请确认该版本确实存在：

npm view @dinglebear/[email protected] version

在 issue #80 解决之前，完整插件无法从 npm 启动。仅包含服务专属技能的插件不依赖该启动器，可继续用于直接对接上游服务的工作流。

如果想直接使用服务脚本而不运行 MCP 服务，请安装一个仅包含技能的插件：

/plugin install sonarr@yarr
/plugin install plex@yarr

客户端配置

stdio

stdio 是首选的本地 MCP 传输方式。它会按需启动 yarr mcp，无需绑定本地 HTTP 端口。

{
  "mcpServers": {
    "yarr": {
      "command": "yarr",
      "args": ["mcp"],
      "env": {
        "RUST_LOG": "info,yarr=debug"
      }
    }
  }
}

Streamable HTTP

如果多个客户端或设备需要共用一个 MCP 端点，请运行持久服务：

YARR_MCP_TOKEN=change-me yarr serve

{
  "mcpServers": {
    "yarr": {
      "url": "http://127.0.0.1:40070/mcp",
      "headers": {
        "Authorization": "Bearer ${YARR_MCP_TOKEN}"
      }
    }
  }
}

HTTP MCP 初始化冒烟测试调用：

curl --fail http://127.0.0.1:40070/mcp \
  -H "Authorization: Bearer $YARR_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-smoke","version":"1"}}}'

请使用 mcporter 等 MCP 客户端进行支持会话的 tools/list 和 Code Mode 调用；原始的一次性 tools/call 并不构成完整的 MCP 会话。

运行时接口

接口	状态	用途
MCP	必需	一个默认的 yarr Code Mode 工具，覆盖整个服务群
CLI	必需	用于调试和自动化的可脚本化对等接口
REST	未提供	上游客户端服务不提供本地 REST 操作 API
Web	核心：未提供	核心服务没有内嵌 UI；经典 Unraid 发行版提供单独的设置／仪表板 Web 界面

设置 YARR_MCP_TOOL_MODE=flat，即可为每个已配置的服务公开一个按操作分发的 MCP 工具，而不是单个 Code Mode 工具。该模式适用于 Labby 等已提供自身发现和沙箱层的网关。codemode 是默认模式，也是独立 MCP 客户端的正确选择。

MCP 工具参考

默认情况下，MCP 会公开一个名为 yarr 的工具。

字段	类型	必填	说明
code	string	是	在进程内 Code Mode 沙盒中执行的 JavaScript 异步箭头函数

在 Code Mode 中，脚本可以使用：

• 每个服务的可调用函数，例如 sonarr.get_series()、 radarr.post_movie({ body })、prowlarr.get_indexer() 和 plex.get_sessions()。
• 精选命令，例如 qbittorrent.download_queue() 和 tautulli.stats_activity()。
• 位于 api.<service>.get/post/put/delete(path, body) 的原始直通辅助函数。
• 用于底层操作分发逃生通道的 callTool(action, params)。
• 用于发现功能的 codemode.search(query) 和 codemode.describe(path)。
• 用于可复用脚本和制品的 codemode.run(name, input)、codemode.snippets() 和 writeArtifact(...)。

生成的可调用函数来自元数据表。它们会保留方法/路径、必需的路径参数、已知的查询名称、JSON 请求体是否存在，以及受限的单文件 multipart 逃生通道。它们不会强制执行所有必需的查询、标头/ Cookie 参数、style/explode 规则、表单架构、媒体类型或响应架构。在依赖生成的操作处理非 JSON 或对序列化敏感的端点之前，请参阅 docs/API.md。

示例：

async () => {
  const queue = await radarr.get_queue();
  await radarr.post_command({
    body: { name: "MoviesSearch", movieIds: [456] }
  });
  return { queued: queue.records?.length };
}

通用操作

这些操作适用于每种已配置的服务类型：

操作	范围	CLI	说明
service_status	yarr:read	yarr <service> status	获取上游服务状态端点
api_get	yarr:write	yarr <service> get --path <path>	代理经过凭据验证的 GET 请求
api_post	yarr:write	yarr <service> post --path <path> --body <json>	代理 POST 请求
api_put	yarr:write	yarr <service> put --path <path> --body <json>	代理 PUT 请求
api_delete	yarr:write	yarr <service> delete --path <path>	代理 DELETE 请求
help	公开	yarr help	返回操作参考

Code Mode 操作

操作	范围	调用方式	说明
codemode	yarr:write	yarr 工具 / yarr codemode --code <JS>	在整个服务集上运行 JS 箭头函数
op	yarr:write	<service>.<operation>() / yarr <service> op <name>	调用生成的 OpenAPI 操作
snippet_list	yarr:read	yarr snippet list / codemode.snippets()	列出已保存的代码片段
snippet_save	yarr:write	yarr snippet save	保存可复用的代码片段
snippet_run	yarr:write	yarr snippet run / codemode.run(name, input)	运行已保存的代码片段
snippet_delete	yarr:write	yarr snippet delete	删除已保存的代码片段

没有 confirm 参数。CLI 破坏性命令会立即分发。 MCP 直接调用和嵌套的 Code Mode 破坏性调用需要征询批准；如果对端无法征询或未获批准，则会默认拒绝。

CLI 参考

CLI 按服务分组：

yarr help
yarr radarr status
yarr sonarr get --path /api/v3/system/status
yarr radarr post --path /api/v3/command --body '{"name":"RefreshMovie"}'
yarr sonarr put --path /api/v3/series/editor --body '{"seriesIds":[1],"qualityProfileId":4}'
yarr radarr delete --path /api/v3/movie/12

# Generated operations for spec-backed services.
yarr sonarr op get_series
yarr radarr op post_command --args '{"body":{"name":"MoviesSearch","movieIds":[456]}}'

# Curated commands for doc-only services.
yarr qbittorrent queue
yarr tautulli activity

# Code Mode and snippets.
yarr codemode --code 'async () => sonarr.get_system_status()'
yarr snippet list

没有 --service 标志。help、codemode 和 snippet 等基础设施命令不依赖服务。

配置

复制 .env.example，或将 config.example.toml 用作起点。常用 环境变量：

YARR_MCP_HOST=127.0.0.1
YARR_MCP_PORT=40070
YARR_MCP_TOKEN=change-me

YARR_SERVICES=sonarr,radarr,prowlarr,tautulli,overseerr,bazarr,tracearr,sabnzbd,qbittorrent,plex,jellyfin
YARR_SONARR_URL=http://sonarr:8989
YARR_SONARR_API_KEY=...
YARR_RADARR_URL=http://radarr:7878
YARR_RADARR_API_KEY=...
YARR_QBITTORRENT_URL=http://qbittorrent:8080
YARR_QBITTORRENT_USERNAME=...
YARR_QBITTORRENT_PASSWORD=...
YARR_PLEX_URL=http://plex:32400
YARR_PLEX_TOKEN=...

支持的服务类型有 sonarr、radarr、prowlarr、tautulli、 overseerr、bazarr、tracearr、sabnzbd、qbittorrent、plex 和 jellyfin。

*_API_KEY 适用于大多数 Arr 风格的服务。qBittorrent 使用用户名/密码 登录。Plex 和 Jellyfin 的令牌标头会单独处理。

YARR_MCP_TOOL_MODE=codemode 是默认设置。只有在网关需要看到各服务单独的 工具时，才使用 YARR_MCP_TOOL_MODE=flat。

身份验证

YARR_MCP_TOKEN 用于在任何 HTTP 绑定地址（包括环回地址）上对 /mcp 进行身份验证。 它具有 YARR_MCP_STATIC_TOKEN_SCOPES 中配置的作用域，该变量默认为只读的 yarr:read。只读 Bearer 部署必须使用 YARR_MCP_TOOL_MODE=flat；使用默认的 Code Mode 界面则必须显式配置 yarr:write 作用域。在 127.0.0.1 或 localhost 上，若未显式配置 Bearer/OAuth，则开发环境会绕过身份验证。

身份验证状态：

状态	条件	行为
LoopbackDev	绑定到环回地址且未显式配置身份验证，或显式配置环回地址免身份验证	无身份验证，无作用域
TrustedGatewayUnscoped	在可信网关后设置 YARR_NOAUTH=true	无本地身份验证或作用域
Mounted bearer	在任何 HTTP 绑定地址上设置 YARR_MCP_TOKEN	使用已配置的静态令牌作用域进行 Bearer 身份验证
Mounted OAuth	在任何 HTTP 绑定地址上设置 YARR_MCP_AUTH_MODE=oauth	OAuth/JWT 身份验证，可选 Bearer

无需身份验证的健康检查端点包括 /health、/ready、/status 和 /metrics。/status 会隐藏机密信息；/metrics 会公开 HTTP 和范围受限的领域指标，必要时应限制其网络访问。

安全与信任模型

机密信息保留在服务端。MCP 客户端只提供操作参数，不提供上游令牌。路径验证会拒绝 apikey=、token= 和 X-Plex-Token 等查询字符串机密信息。

操作层面向所有人开放 help，但已挂载的 HTTP 传输仍要求进行 Bearer 或 OAuth 传输身份验证。service_status 需要 yarr:read。 带凭证的透传、生成的操作、精选写入操作和 Code Mode 均需要 yarr:write；写入权限包含读取权限。

生成的 DELETE 操作、api_delete、download_remove、 stats_delete_image_cache 和 trace_terminate_stream 均具有破坏性。CLI 命令会立即执行这些操作。MCP 调用方会在实际执行点收到交互式征询提示，包括在 Code Mode 内部；不存在可绕过此提示的调用参数或嵌套 callTool 路径。

响应在返回给 MCP 客户端之前，会由共享的令牌限制层进行截断。

架构

MCP shim (src/mcp/tools.rs)   CLI shim (src/cli.rs)
  JSON args -> dispatch          argv -> dispatch
        \                          /
         execute_service_action (src/actions/dispatch.rs)
             shared validation + curated-command dispatch
                          |
         YarrService (src/app.rs + src/app/*.rs)
           validation, service lookup, response shaping
                          |
         YarrClient (src/yarr.rs)
           network calls and auth headers

src/mcp.rs 和 src/cli.rs 是轻量门面，负责重新导出各自的子模块。execute_service_action 从结构上确保 CLI 与 MCP 的行为一致，而非依赖手动同步。

服务层负责：

• 受支持的服务目录和配置查找
• 安全路径验证
• 凭证脱敏
• qBittorrent 登录流程
• 响应规范化

发布约定

发布身份信息以 Cargo.toml、 Cargo.lock、xtask/Cargo.toml、.release-please-manifest.json、 packages/yarr-mcp/package.json 和 server.json 中共享的版本号为准。

生成的代码和文档必须根据已提交的源输入重新生成，不得手动修改：

• 生成的 OpenAPI 操作位于 src/openapi/generated/ 下，来源于 specs/ 中的供应商规范。
• 精选操作位于手写的操作注册表和文档中。
• 插件清单不包含版本号；市场会根据 git 提交 SHA 推导插件版本。
• npm 包版本必须与 GitHub Release 标签一致。
• server.json 必须在 ai.dinglebear/yarr 注册表标识下指定准确的 yarr-mcp npm 版本和 stdio 启动约定。
• Docker 镜像路径为 ghcr.io/dinglebear-ai/yarr；生产部署使用已提升的不可变 @sha256: 摘要。

开发

cargo run -- help
cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release

更改生成的操作时：

cargo xtask gen-openapi
cargo xtask tool-docs
cargo test --test parity

更改插件打包时：

cargo test --test plugin_contract
cargo test --test template_invariants

验证

提交文档更改前，请使用 README 指南检查器：

python3 /home/jmagar/workspace/soma/scripts/check-readme-guide.py README.md

对于涉及发布的工作，请使用包和 Rust 检查：

npm --prefix packages/yarr-mcp run check
cargo fmt --check
cargo check
cargo test
git diff --check

进行实际安装验证时，请验证原生安装程序；只有在准确匹配的版本依赖解析成功后，才测试 npm 安装路径：

curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/yarr/main/install.sh | bash
yarr --version

YARR_VERSION=2.1.0
npm view "@dinglebear/yarr@${YARR_VERSION}" version
npx -y "@dinglebear/yarr@${YARR_VERSION}" mcp

文档更改还必须通过仓库本地链接和锚点检查：

python3 scripts/check-doc-links.py

部署

作为持久运行的 HTTP MCP 服务启动：

YARR_MCP_HOST=0.0.0.0 \
YARR_MCP_PORT=40070 \
YARR_MCP_TOKEN=change-me \
YARR_MCP_STATIC_TOKEN_SCOPES=yarr:read \
YARR_MCP_TOOL_MODE=flat \
yarr serve

Docker Compose 部署的相关内容见 docker-compose.yml、 docker-compose.prod.yml、docs/DOCKER.md 和 docs/DEPLOYMENT.md。 在环回地址以外公开 yarr 时，生产环境部署应将其置于可信的反向代理或 MCP 网关之后。

故障排查

• HTTP MCP 返回 401 或 403：确认 YARR_MCP_TOKEN、OAuth 模式和 网关请求头。

• unknown service：确认服务已列在 YARR_SERVICES 中，并且有匹配的 YARR_<SERVICE>_URL。

• 上游返回 401：确认服务器环境中配置了该服务专用的 API 密钥或令牌，而不是在工具参数中提供。

• query-string secret rejected：从 --path 中移除令牌，并将其放入配置中。

• 插件技能无法连接服务：其每个服务对应的配置 JSON ~/.config/lab-<service>/config.json 缺失或已过期。该文件由插件的 SessionStart / ConfigChange 钩子写入，因此请启动新会话（或更改 插件设置）以刷新配置。若要手动重建，请自行导出设置——脚本读取 CLAUDE_PLUGIN_OPTION_*，该变量仅由钩子设置：

  CLAUDE_PLUGIN_OPTION_SONARR_URL=https://sonarr.example.com \
  CLAUDE_PLUGIN_OPTION_SONARR_API_KEY=… \
    bash plugins/sonarr/scripts/setup.sh
  

  技能脚本通过 Bash 工具运行，该工具不会收到 CLAUDE_PLUGIN_OPTION_* 变量——只有钩子进程会收到。这就是这些 插件需要钩子的原因：它是唯一能将 sensitive: true 值传递给技能的渠道，因为敏感值永远不会替换进技能正文，而且这些插件没有 MCP 服务来接收 ${user_config.*} 环境变量块。

• Code Mode 找不到可调用项：使用 codemode.search(...) 和 codemode.describe(...)；生成的名称遵循上游 OpenAPI 操作 ID 的规范化形式。

• npm 或完整插件报告 E404/ETARGET：使用 npm view @dinglebear/[email protected] version 检查确切固定版本的启动器。问题 #80 仍未解决前，不要回退到未固定的 latest；请使用原生二进制文件。

相关服务

• soma - 用于由提供方支持的 MCP 服务的 RMCP 运行时。
• unifi-rmcp - UniFi 控制器 REST API 桥接服务。
• tailscale-rmcp - 用于设备、用户和 tailnet 操作的 Tailscale API 桥接服务。
• unraid-rmcp - 用于 NAS 和服务器管理的 Unraid GraphQL 桥接服务。
• apprise-rmcp - 面向多种消息投递后端的 Apprise 通知分发桥接服务。
• gotify-rmcp - 用于发送通知、管理消息、应用和客户端的 Gotify 推送通知桥接服务。
• arcane-rmcp - 用于容器及相关资源的 Arcane Docker 管理桥接服务。
• ytdl-rmcp - 媒体下载和元数据工作流服务。
• synapse-rmcp - 用于 scout 和 flux 操作的本地 Synapse 工作流服务。
• cortex - Syslog 和家庭实验室日志聚合 MCP 服务。
• axon - RAG、爬取、抓取、提取和语义搜索项目。
• labby - 家庭实验室控制平面和 MCP 网关项目。
• lumen - 本地语义代码搜索 MCP 服务。

文档

权威文档分工如下：

• docs/README.md 是面向受众的文档索引。
• docs/DOCS.md 规定权威性、生成文档的规则、时效性检查，以及新增文档的归属位置。
• docs/API.md 介绍操作契约和 Code Mode 调用形式。
• docs/CONFIG.md、docs/ENV.md 和 docs/AUTH.md 介绍配置、环境变量、身份验证状态和工具模式。
• docs/QUICKSTART.md 介绍原生、源码、指定精确版本的 npm 和 Unraid 首次运行路径。
• docs/MCP_SCHEMA.md 和 docs/TOOLS_ACTIONS_ENDPOINTS.md 是经过检查的架构和操作参考文档。
• docs/DEPLOYMENT.md、docs/DOCKER.md 和 docs/SYSTEMD.md 介绍生产环境运行方式。
• docs/CI.md、docs/SCRIPTS.md 和 docs/runbooks/ 介绍验证、发布、事件处理和回滚。
• docs/PATTERNS.md 汇集 RMCP 服务系列共用的约定。
• docs/PLUGINS.md、plugins/README.md 和 plugins/yarr/README.md 介绍市场打包和启动器可用性。
• unraid-plugin/README.md 是经典 Unraid 发行版的运维、API、恢复、验证和发布指南。
• CLAUDE.md 保存仓库本地的 Agent 记忆，以及“如何添加操作”检查清单。

许可证

本项目中由 Dinglebear 原创撰写的部分采用 AGPL-3.0-only 许可。对于需要 AGPL 以外条款的组织，可提供单独的商业许可。第三方材料仍遵循其原始许可证。请参阅 LICENSING.md。