Overseerr MCP

一个用于 Overseerr 的模型上下文协议 (MCP) 集成，它允许通过 Claude AI 与您的媒体请求系统进行自然语言交互。此服务器允许您搜索电影和电视节目、发出媒体请求以及使用对话式语言管理您的 Overseerr 实例。

示例对话

以下是一些您可以使用此服务器与 Claude 进行的示例对话：

您：你能找到最近的科幻电影吗？
Claude：让我搜索最近的科幻电影...
[使用 overseerr:search 查找最近的科幻电影]

您：看起来不错！你能请求第二个吗？
Claude：我会为您请求这部电影...
[使用 overseerr:request 提交媒体请求]

您：有哪些关于烹饪的电视节目？
Claude：我将搜索与烹饪相关的电视节目...
[使用 type='tv' 的 overseerr:search 查找烹饪节目]

功能

媒体搜索

• 搜索电影、电视节目和人物
• 获取有关媒体的详细信息，包括：
  • 标题和发布日期
  • 剧情概述
  • 可用性状态
  • 请求状态
• 按媒体类型过滤（电影/电视/人物）
• 自然语言查询（例如，“查找最近的科幻电影”或“搜索类似《绝命毒师》的节目”）

媒体请求

• 请求电影和电视节目
• 为电视节目指定单个季
• 跟踪请求状态
• 获取有关请求更新的通知
• 自然语言请求（例如，“请求最新的蝙蝠侠电影”或“将《继承之战》添加到我的观看列表”）

集成

• 通过 stdio 传输实现无缝的 Claude AI 集成
• 与您的 Overseerr 实例进行实时交互
• 安全的 API 密钥处理
• 速率限制和错误处理
• 通过环境变量轻松配置

设置

前提条件

• Node.js
• pnpm
• Claude Desktop
• Overseerr 实例

快速开始

1. 安装依赖项：

pnpm install

2. 构建项目：

pnpm build

3. 配置环境：

# 复制模板
cp .env.template .env

# 使用您的值编辑 .env
OVERSEERR_URL=your_overseerr_url
OVERSEERR_API_KEY=your_api_key

4. 配置 Claude Desktop：

Linux/Mac：

{
  "overseerr": {
    "command": "node",
    "args": ["/path/to/overseerr/packages/server/dist/index.js"],
    "cwd": "/path/to/overseerr",
    "transport": {
      "type": "stdio"
    },
    "env": {
      "OVERSEERR_URL": "your_overseerr_url",
      "OVERSEERR_API_KEY": "your_api_key"
    }
  }
}

Windows（注意双反斜杠）：

{
  "overseerr": {
    "command": "node",
    "args": ["C:\\path\\to\\overseerr\\packages\\server\\dist\\index.js"],
    "cwd": "C:\\path\\to\\overseerr",
    "transport": {
      "type": "stdio"
    },
    "env": {
      "OVERSEERR_URL": "your_overseerr_url",
      "OVERSEERR_API_KEY": "your_api_key"
    }
  }
}

5. 启动服务器：

pnpm start

技术细节

项目结构

packages/
├── config/      # 配置管理
├── overseerr/   # Overseerr API 客户端
├── server/      # MCP 服务器实现
└── shared/      # 共享类型和实用程序

可用工具

搜索媒体 (overseerr:search)

在 Overseerr 数据库中搜索电影、电视节目和人物。

{
  // 搜索查询 - 可以是标题、人物或一般描述
  query: string,
  
  // 可选：按类型过滤
  // - 'movie': 仅搜索电影
  // - 'tv': 仅搜索电视节目
  // - 'person': 仅搜索人物
  type?: 'movie' | 'tv' | 'person'
}

示例查询：

• "搜索《盗梦空间》"
• "查找 2023 年的电视节目"
• "寻找汤姆·汉克斯的电影"

请求媒体 (overseerr:request)

请求将电影或电视节目添加到您的媒体库。

{
  // 要请求的媒体的 TMDB ID
  mediaId: number,
  
  // 请求的媒体类型
  // - 'movie': 请求电影
  // - 'tv': 请求电视节目
  mediaType: 'movie' | 'tv',
  
  // 可选：对于电视节目，指定要请求的季
  // 如果未提供，则请求所有可用的季
  seasons?: number[]
}

示例请求：

• 请求电影：“请求《黑客帝国》”
• 请求特定季：“添加《办公室》第 1-3 季”
• 请求所有季：“请求《绝命毒师》全集”

配置

环境变量

• OVERSEERR_URL：您的 Overseerr 实例 URL
• OVERSEERR_API_KEY：您的 Overseerr API 密钥

错误处理

服务器实现了强大的错误处理：

• 带有有意义消息的 API 错误
• 速率限制保护
• 请求验证
• 连接错误恢复

贡献

1. Fork 存储库
2. 创建一个功能分支
3. 提交您的更改
4. 推送到分支
5. 创建一个 Pull Request

许可证

MIT