Sonarr & Radarr MCP Server

Sonarr&Radarr MCP服务器

一个安全的、生产就绪的模型上下文协议（MCP）服务器，用于与Sonarr和Radarr API交互。此服务器使Claude能够查询您的媒体库，检查最近添加的内容，查看即将发布的版本，并执行基本的管理任务。

特性

索纳尔

• 获取最近添加的电视剧
• 查看即将播出的剧集日历
• 在您的库中搜索系列
• 检查系统状态和磁盘空间
• 查看下载队列
• 刷新系列元数据
• 触发事件搜索

雷达

• 获取最近添加的电影
• 查看即将上映的电影
• 在您的库中搜索电影
• 检查系统状态和磁盘空间
• 查看下载队列
• 刷新电影元数据
• 触发电影搜索

安全特性

此MCP服务器在构建时优先考虑安全性：

• 非根容器执行：以用户ID 1000（非root）运行
• 只读根文件系统：容器文件系统是不可变的
• 无特权升级：容器无法获得其他特权
• 能力下降：所有Linux功能都下降了
• 秘密管理：存储在Kubernetes机密中的API密钥
• 网络策略：仅限制网络访问必要的服务
• 资源限制：CPU和内存限制可防止资源耗尽
• 安全默认值：从头开始遵循安全最佳做法

先决条件

• Docker（用于容器化）
• Kubernetes集群（用于部署）
• 具有API访问权限的Sonarr实例
• 具有API访问权限的Radarr实例
• Python 3.12+（用于本地开发）

快速开始

1.克隆和配置

git clone 
cd mcp-servarr

2.设置环境变量

复制示例环境文件：

cp .env.example .env

编辑 .env 根据您的实际值：

# Sonarr Configuration
SONARR_URL=http://your-sonarr-host:8989
SONARR_API_KEY=your-sonarr-api-key

# Radarr Configuration
RADARR_URL=http://your-radarr-host:7878
RADARR_API_KEY=your-radarr-api-key

查找API密钥：

• 声纳：设置→ 将军→ 安全→ API密钥
• 雷达：设置→ 将军→ 安全→ API密钥

3.构建Docker镜像

docker build -t mcp-servarr:latest .

4.使用Docker Compose进行本地测试

docker-compose up

Kubernetes部署

1.更新机密

编辑 k8s/deployment.yaml 并替换Secret中的占位符API密钥：

stringData:
  SONARR_URL: "http://sonarr.media.svc.cluster.local:8989"
  SONARR_API_KEY: "your-actual-sonarr-api-key"
  RADARR_URL: "http://radarr.media.svc.cluster.local:7878"
  RADARR_API_KEY: "your-actual-radarr-api-key"

安全说明： 用于生产，使用 kubectl create secret 而不是将秘密存储在YAML中：

kubectl create secret generic mcp-servarr-secrets \
  --namespace=mcp-servarr \
  --from-literal=SONARR_URL='http://sonarr:8989' \
  --from-literal=SONARR_API_KEY='your-key' \
  --from-literal=RADARR_URL='http://radarr:7878' \
  --from-literal=RADARR_API_KEY='your-key'

2.部署到Kubernetes

kubectl apply -f k8s/deployment.yaml

3.验证部署

kubectl get pods -n mcp-servarr
kubectl logs -n mcp-servarr deployment/mcp-servarr

连接到克劳德

要将此MCP服务器与Claude Desktop一起使用，请将其添加到您的MCP设置中：

使用Docker

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "mcp-servarr": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file", "/path/to/your/.env",
        "mcp-servarr:latest"
      ]
    }
  }
}

使用Python（开发）

{
  "mcpServers": {
    "mcp-servarr": {
      "command": "python",
      "args": [
        "/path/to/mcp-servarr/src/server.py"
      ],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-key",
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-key"
      }
    }
  }
}

使用示例

连接到Claude后，您可以提出以下问题：

• “本周Sonarr增加了哪些电视节目？”
• “未来30天有什么电影上映？”
• “在我的图书馆里搜索《绝命毒师》”
• “Radarr中当前正在下载什么？”
• “显示Sonarr的系统状态”
• “刷新序列ID 123的元数据”

api参考

环境变量

\*必须至少配置一个服务（Sonarr或Radarr）

可用工具

Sonarr工具

• sonarr_get_recent_series -获取最近添加的系列
• sonarr_get_calendar -获取即将播出的剧集
• sonarr_search_series -搜索系列
• sonarr_get_system_status -获取系统状态
• sonarr_get_queue -获取下载队列
• sonarr_refresh_series -刷新系列元数据
• sonarr_search_episodes -搜索缺失的剧集

雷达工具

• radarr_get_recent_movies -获取最近添加的电影
• radarr_get_calendar -获取即将发布的版本
• radarr_search_movies -搜索电影
• radarr_get_system_status -获取系统状态
• radarr_get_queue -获取下载队列
• radarr_refresh_movie -刷新电影元数据
• radarr_search_movie -搜索电影

发展

地方发展设置

1. 创建虚拟环境：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

1. 安装依赖项：

pip install -r requirements.txt

1. 运行服务器：

export SONARR_URL=http://localhost:8989
export SONARR_API_KEY=your-key
export RADARR_URL=http://localhost:7878
export RADARR_API_KEY=your-key
python src/server.py

测试

使用MCP检查器测试服务器：

npx @modelcontextprotocol/inspector python src/server.py

故障排除

连接问题

问题：无法连接到Sonarr/Radarr

解决方案:

• 验证URL是否正确（包括http://或https://）
• 检查API密钥是否有效
• 确保Sonarr/Radarr可从集装箱进入
• 检查Kubernetes中的网络策略

权限错误

问题：容器失败，出现权限错误

解决方案:

• 验证容器是否以非root身份运行（UID 1000）
• 检查卷装载权限
• 确保只读文件系统配置正确

API速率限制

问题：获取速率受API限制

解决方案:

• 增加 REQUEST_TIMEOUT 如果请求超时
• 减少查询频率
• 检查Sonarr/Radarr日志是否存在问题

安全考虑

生产部署检查表

• \[\]将Kubernetes机密用于API密钥（而不是ConfigMaps）
• \[\]启用Pod安全标准（受限配置文件）
• \[\]配置网络策略以限制出口流量
• \[\]设置适当的资源限制
• \[\]启用审核日志记录
• \[\]使用私有容器注册表
• \[\]扫描图像以查找漏洞
• \[\]定期旋转API键
• \[\]对Sonarr/Radarr连接使用TLS
• \[\]实施监控和警报

API密钥安全

永远不要将API密钥提交到版本控制！

生产：

1. 使用Kubernetes机密
2. 考虑使用秘密管理器（保险库、密封秘密等）
3. 定期旋转按键
4. 针对不同的环境使用单独的API密钥
5. 在Sonarr/Radarr中启用API密钥身份验证登录

贡献

欢迎投稿！请随时提交拉取请求。

指南

• 遵循现有代码样式
• 为新功能添加测试
• 更新文档
• 确保安全最佳实践
• 在Docker和Kubernetes中进行测试

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题、疑问或贡献，请在GitHub上打开问题。

致谢

• 与 模型上下文协议SDK
• 用途 API声纳
• 用途 Radarr API公司