AI导哈

媒体库管理服务器

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

  • by bdfrost
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 bdfrost/mcp_servarr

使用说明

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 <your-repo-url>
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_URL 没有* - Sonarr基本URL（例如。，http://sonarr:8989)
SONARR_API_KEY 无* - Sonarr API密钥
RADARR_URL 无* - Radarr基本URL（例如。，http://radarr:7878)
RADARR_API_KEY 无* - Radarr API密钥
REQUEST_TIMEOUT 否 30 HTTP请求超时（秒）

*必须至少配置一个服务（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上打开问题。

致谢

相关 MCP