mcp-arr

MCP *arr 服务器

*arr 媒体管理套件的 MCP 服务，支持 Sonarr、Radarr、Lidarr 和 Prowlarr。

同时支持适用于 Claude/Codex 类客户端的本地 stdio 模式，以及适用于 ChatGPT 连接器等托管 MCP 客户端的远程 HTTP 模式。

为什么使用它？

• 统一媒体管理——通过一个界面控制所有 *arr 应用
• 自然语言查询——用日常语言询问媒体库信息
• 跨服务搜索——同时搜索电视、电影和音乐内容
• 下载监控——查看所有服务的队列状态和进度
• 日历集成——查看所有媒体类型的即将发布内容
• 配置审查——获取 AI 提供的设置优化建议
• 灵活配置——仅启用你使用的服务

功能

类别	功能
Sonarr（电视）	列出剧集系列、查看分集、搜索剧集、触发下载、查看队列、查看日历、审查设置
Radarr（电影）	列出电影、搜索影片、触发下载、查看队列、查看上映信息、审查设置
Lidarr（音乐）	列出艺人、查看专辑、搜索音乐人、触发下载、查看队列、查看日历、审查设置
Prowlarr（索引器）	列出索引器、跨所有跟踪器搜索、测试运行状况、查看统计信息
跨服务	检查状态、跨所有已配置服务统一搜索
配置	质量配置文件、下载客户端、命名约定、运行状况检查、存储信息
TRaSH Guides	参考质量配置文件、自定义格式和命名约定，并与推荐设置进行比较

先决条件

• Node.js 18+
• 至少运行一个具有 API 访问权限的 *arr 应用：
  • 用于电视剧的 Sonarr
  • 用于电影的 Radarr
  • 用于音乐的 Lidarr
  • 用于索引器管理的 Prowlarr

安装

使用 npm（推荐）

npx mcp-arr-server

远程 HTTP 模式

MCP_TRANSPORT=http PORT=3000 npx mcp-arr-server

默认情况下，远程服务监听 127.0.0.1:3000，并在 /mcp 上提供 MCP 服务。

远程模式的环境变量：

• MCP_TRANSPORT=http 用于启用远程 Streamable HTTP 传输
• HOST 用于覆盖绑定主机（默认值为 127.0.0.1）
• PORT 用于覆盖端口（默认值为 3000）
• MCP_PATH 用于覆盖 MCP 端点路径（默认值为 /mcp）

Docker

每次发布时都会将预构建镜像发布到 GitHub Container Registry。你无需 自行构建：

docker pull ghcr.io/aplaceforallmystuff/mcp-arr:latest

标签遵循发布版本——latest、1、1.7，以及各个精确版本（例如 1.7.3）。 如果希望更新可控且没有意外，请固定到主版本或次版本标签。

以本地 stdio 模式运行：

docker run --rm -i \
  -e SONARR_URL=http://host.docker.internal:8989 \
  -e SONARR_API_KEY=your-sonarr-api-key \
  ghcr.io/aplaceforallmystuff/mcp-arr:latest

以远程 HTTP 模式运行：

docker run --rm -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e PORT=3000 \
  -e SONARR_URL=http://host.docker.internal:8989 \
  -e SONARR_API_KEY=your-sonarr-api-key \
  ghcr.io/aplaceforallmystuff/mcp-arr:latest

最精简的 docker-compose.yml：

services:
  mcp-arr:
    image: ghcr.io/aplaceforallmystuff/mcp-arr:latest
    ports:
      - "3000:3000"
    environment:
      MCP_TRANSPORT: http
      HOST: 0.0.0.0
      PORT: 3000
      SONARR_URL: http://host.docker.internal:8989
      SONARR_API_KEY: your-sonarr-api-key
      RADARR_URL: http://host.docker.internal:7878
      RADARR_API_KEY: your-radarr-api-key

自行构建

仅在你要基于尚未发布的更改进行开发时才需要：

docker build -t mcp-arr .

从源代码构建

git clone https://github.com/aplaceforallmystuff/mcp-arr.git
cd mcp-arr
npm install
npm run build

配置

获取 API 密钥

每个 *arr 应用都可在 Settings > General > Security 中找到 API 密钥：

1. 打开 *arr 应用的 Web 界面
2. 前往 Settings > General
3. 在 Security 部分找到 API Key
4. 复制 API 密钥以用于配置

用于 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "arr": {
      "command": "npx",
      "args": ["-y", "mcp-arr-server"],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-sonarr-api-key",
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-radarr-api-key",
        "LIDARR_URL": "http://localhost:8686",
        "LIDARR_API_KEY": "your-lidarr-api-key",
        "PROWLARR_URL": "http://localhost:9696",
        "PROWLARR_API_KEY": "your-prowlarr-api-key"
      }
    }
  }
}

用于 Claude Code

添加到 ~/.claude.json：

{
  "mcpServers": {
    "arr": {
      "command": "npx",
      "args": ["-y", "mcp-arr-server"],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-sonarr-api-key",
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-radarr-api-key"
      }
    }
  }
}

注意：仅配置正在运行的服务。服务端会根据你提供的环境变量自动检测可用服务。

仅 TRaSH 模式：如果你未配置任何 *arr 服务，服务端仍会启动，并提供 TRaSH Guides 参考工具以及通用的 search 和 fetch。

ChatGPT / 远程 MCP

要将 mcp-arr 与 ChatGPT 搭配使用，请在可访问的主机上以远程 HTTP 模式运行服务端，并将 ChatGPT 连接到 /mcp 端点。

服务端现在提供 ChatGPT 风格远程 MCP 集成所需的通用 search 和 fetch 工具：

• search 可发现匹配的 *arr 媒体和 TRaSH 配置文件
• fetch 可返回所选搜索结果的结构化详情

现有的服务专用工具仍可用于功能更丰富的本地工作流或高级用户工作流。

使用示例

媒体库管理

• “显示我的所有电视剧”
• “Radarr 里有哪些电影？”
• “列出我的音乐库中的所有艺人”

搜索和添加内容

• “在 Sonarr 上搜索科幻剧集”
• “查找 90 年代的动作电影”
• “将这部剧添加到我的电视剧库”
• “将那部电影添加到 Radarr”
• “搜索爵士专辑并添加这位艺人”
• “使用我的 ‘4k’ 标签添加这部电影”
• “我在 Sonarr 中有哪些标签？”

下载队列

• “现在正在下载什么？”
• “查看 Sonarr 队列”
• “显示 Radarr 下载进度”

即将上映

• “这周有哪些电视剧集即将播出？”
• “显示即将上映的电影”
• “这个月有新专辑发行吗？”

下载内容

• “这部剧有哪些剧集我还没有？”
• “下载该剧缺失的剧集”
• “搜索这部特定电影”
• “获取我缺少的那张专辑”

索引器管理

• “我的索引器运行正常吗？”
• “我的索引器表现如何？”
• “测试所有 Prowlarr 索引器”

配置检查

• “检查我的 Sonarr 配置并提出改进建议”
• “显示我在 Radarr 中的质量配置文件”
• “我的 Lidarr 有健康问题吗？”
• “我为电视剧使用了什么命名规则？”
• “帮我理解质量配置文件——为什么我获取不到 4K 内容？”
• “检查我的下载客户端配置”
• “我的根文件夹还剩多少可用空间？”

跨服务

• “检查我所有 *arr 服务的状态”
• “在所有服务中搜索 ‘comedy’”

可用工具

通用工具

工具	描述
arr_status	获取所有已配置 *arr 服务的连接状态
arr_search_all	同时搜索所有已配置服务
search	为 ChatGPT 等远程 MCP 客户端提供的通用发现工具
fetch	获取 search 返回项目的通用详情

Sonarr 工具（电视节目）

工具	描述
sonarr_get_series	列出媒体库中的所有电视节目
sonarr_search	按名称搜索电视节目（返回用于添加的 tvdbId）
sonarr_add_series	将电视节目添加到 Sonarr（支持标签）
sonarr_get_root_folders	获取用于添加电视节目的可用根文件夹
sonarr_get_quality_profiles	获取用于添加电视节目的可用质量配置文件
sonarr_get_queue	查看当前下载队列，支持使用 limit 和 offset 分页
sonarr_get_calendar	查看即将播出的剧集
sonarr_get_episodes	列出某个电视节目的剧集（显示缺失与可用状态）
sonarr_search_missing	触发对某个电视节目所有缺失剧集的搜索
sonarr_search_episode	触发对指定剧集的搜索
sonarr_refresh_series	触发对 Sonarr 中指定电视节目的元数据刷新

Radarr 工具（电影）

工具	描述
radarr_get_movies	列出媒体库中的所有电影
radarr_search	按名称搜索电影（返回用于添加的 tmdbId）
radarr_add_movie	将电影添加到 Radarr（支持标签）
radarr_get_root_folders	获取用于添加电影的可用根文件夹
radarr_get_quality_profiles	获取用于添加电影的可用质量配置文件
radarr_get_queue	查看当前下载队列，支持使用 limit 和 offset 分页
radarr_get_calendar	查看即将上映的影片
radarr_search_movie	触发搜索，以下载媒体库中的电影
radarr_search_movies	一次性批量触发对多个电影 ID 的搜索
radarr_update_movie	更新电影的质量配置文件、监控状态、最低可用性、标签或路径
radarr_delete_queue_item	从下载队列中移除项目（可选择将该发布加入黑名单）
radarr_refresh_movie	触发对 Radarr 中指定电影的元数据刷新

Lidarr 工具（音乐）

工具	描述
lidarr_get_artists	列出媒体库中的所有艺人
lidarr_search	按名称搜索艺人（返回用于添加的 foreignArtistId）
lidarr_add_artist	将艺人添加到 Lidarr（支持标签）
lidarr_get_root_folders	获取用于添加艺人的可用根文件夹
lidarr_get_quality_profiles	获取用于添加艺人的可用质量配置文件
lidarr_get_metadata_profiles	获取用于添加艺人的可用元数据配置文件
lidarr_get_queue	查看当前下载队列，支持使用 limit 和 offset 分页
lidarr_get_albums	列出某位艺人的专辑（显示缺失与可用状态）
lidarr_search_album	触发对指定专辑的搜索
lidarr_search_missing	触发对某位艺人所有缺失专辑的搜索
lidarr_get_calendar	查看即将发行的专辑

Prowlarr 工具（索引器）

工具	描述
prowlarr_get_indexers	列出所有已配置的索引器
prowlarr_search	跨所有索引器搜索
prowlarr_test_indexers	测试所有索引器并返回健康状态
prowlarr_get_stats	获取索引器统计信息（查询、抓取、失败）

配置审查工具

这些工具适用于 Sonarr、Radarr 和 Lidarr。将 {service} 替换为服务名称（例如，sonarr_get_quality_profiles）。

工具	描述
{service}_get_quality_profiles	详细的质量配置文件信息，包括允许的质量和自定义格式评分
{service}_get_health	应用检测到的健康检查警告和问题
{service}_get_root_folders	存储路径、可用空间和可访问状态
{service}_get_download_clients	下载客户端配置和设置
{service}_get_naming	文件和文件夹命名约定
{service}_get_tags	用于内容整理的标签定义
{service}_review_setup	供 AI 辅助设置分析的完整配置转储

{service}_review_setup 工具可通过一次调用返回所有配置，从而支持通过自然语言对话优化设置。Claude 可以分析你的质量配置文件、提出改进建议、解释为何某些内容无法被抓取，并帮助配置自定义格式等复杂设置。

⚠️ 免责声明：配置审查工具仅提供对你的 *arr 设置的只读访问权限。任何配置更改都必须直接在 *arr 应用界面中进行。AI 的建议仅供参考——进行重大更改前，请务必备份配置。维护者不对因遵循 AI 生成的建议而导致的任何配置更改、数据丢失或其他问题负责。

TRaSH Guides 工具

通过 Claude 或 ChatGPT，直接访问 TRaSH Guides 中由社区整理的质量配置文件、自定义格式和命名约定。这些工具无需任何 *arr 配置即可使用——它们会从 TRaSH Guides GitHub 仓库获取参考数据。

工具	描述
trash_list_profiles	列出 Radarr 或 Sonarr 可用的 TRaSH 质量配置文件
trash_get_profile	获取包含自定义格式、评分和质量设置的详细配置文件
trash_list_custom_formats	列出自定义格式，可选按类别筛选（hdr、audio、resolution 等）
trash_get_naming	获取适用于 Plex、Emby、Jellyfin 或标准格式的推荐命名约定
trash_get_quality_sizes	获取各质量级别推荐的最小、最大和首选大小
trash_compare_profile	将你的配置文件与 TRaSH 推荐进行比较（需要配置 *arr）
trash_compare_naming	将你的命名配置与 TRaSH 推荐进行比较（需要配置 *arr）

使用示例：

• “TRaSH 为 4K 电影推荐哪些质量配置文件？”
• “显示 remux-web-1080p 配置文件的详细信息”
• “将我的 Radarr 配置文件 4 与 TRaSH 的 uhd-bluray-web 配置文件进行比较”
• “Plex 应使用什么命名约定？”
• “列出 Radarr 的 HDR 相关自定义格式”

数据缓存 1 小时，以尽量减少 GitHub API 调用。

开发

# Watch mode for development
npm run watch

# Build TypeScript
npm run build

# Run locally
SONARR_URL="http://localhost:8989" SONARR_API_KEY="your-key" node dist/index.js

故障排除

“未配置任何 *arr 服务”

请确保至少设置了一组 URL 和 API_KEY 环境变量：

SONARR_URL="http://localhost:8989"
SONARR_API_KEY="your-api-key"

“API 错误：401 Unauthorized”

API 密钥不正确。请在 *arr 应用的 Settings > General > Security 中验证。

“fetch failed” 或 “ECONNREFUSED”

*arr 应用未运行或 URL 不正确。请确认：

• 应用正在运行
• URL 和端口正确
• 没有防火墙阻止连接

“未配置 Sonarr/Radarr 等服务”

你尝试使用尚未配置的服务工具。请添加相应的 URL 和 API_KEY 环境变量。

需要帮助构建或保护 MCP 服务吗？

我构建并维护像这样的 MCP 服务，也会审查 AI 和 Agent 配置的安全性。如果你的团队需要自定义服务、集成，或对已有服务进行安全审查，请访问 jimchristian.net/work 或预约一次沟通会。

许可证

MIT - 详情请参阅 LICENSE。

链接

• Servarr Wiki - 所有 *arr 应用的文档
• TRaSH Guides - 质量配置文件、自定义格式和设置指南
• Sonarr API 文档
• Model Context Protocol
• GitHub 仓库