jmagar_overseerr-mcp-server

🚀 Overseerr MCP 中文文档

Overseerr MCP 是集成于 Overseerr 的模型上下文协议 (MCP)，借助 Claude AI 实现与媒体请求系统的自然语言交互。用户可通过对话式语言搜索影视、提交媒体请求，还能管理 Overseerr 实例。

🚀 快速开始

先决条件

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

快速开始步骤

1. 安装依赖项：

pnpm install

2. 构建项目：

pnpm build

3. 配置环境变量：

export OVERSEERR_URL=your-overseerr-instance-url
export OVERSEERR_API_KEY=your-overseerr-api-key

4. 运行服务器：

pnpm start

✨ 主要特性

媒体搜索

• 可在电影、电视剧和人物间进行搜索。
• 能获取媒体详细信息，涵盖标题、发布日期、剧情概述、可用性状态和请求状态。
• 支持按媒体类型（电影/电视剧/人）过滤。
• 支持自然语言查询，如“查找近期的科幻电影”或“搜索类似于《绝命毒师》的节目”。

媒体请求

• 可请求电影和电视剧。
• 能为电视剧指定具体赛季。
• 可跟踪请求状态，获取请求更新通知。
• 支持自然语言请求，如“请求最新的蝙蝠侠电影”或“将《继承之战》添加到我的观看列表中”。

集成

• 通过 stdio 运输与 Claude AI 无缝集成。
• 可实时与 Overseerr 实例交互。
• 具备安全的 API 密钥处理机制。
• 有速率限制和错误处理功能。
• 可通过环境变量进行简单配置。

💻 使用示例

基础用法

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

你: 你能找到任何近期的科幻电影吗?
Claude: 让我为您搜索最近的科幻影片...
[使用 overseerr:search 查找近期的科幻电影]

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

你: 有哪些关于烹饪的可用电视剧?
Claude: 让我搜索与烹饪相关的电视剧...
[使用 overseerr:search 并设置 type='tv' 来查找烹饪节目]

🔧 技术细节

项目结构

• src/: 包含所有源代码文件，包括路由、服务和中间件。
• public/: 存放静态资源，如 CSS 和 JavaScript 文件。
• package.json: 定义了项目的依赖项和脚本。

技术工具

搜索媒体

接口定义：

interface SearchQuery {
  term: string;
  type?: 'movie' | 'tv' | 'person';
}

示例查询：

• 搜索电影：“搜索《泰坦尼克号》”
• 搜索电视剧：“查找《权力的游戏》”

请求媒体

接口定义：

interface RequestPayload {
  title: string;
  year: number;
  imdbId?: string;
  seasons?: number[];
}

示例请求：

• 请求电影：“请求《阿凡达》”
• 请求特定赛季：“添加《老友记》的第1到第5季”
• 请求所有赛季：“请求《越狱》全套”

错误处理

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

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

📚 详细文档

配置信息

环境变量

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

贡献指南

1. 叉取仓库
2. 创建功能分支
3. 提交您的更改
4. 推送到分支
5. 创建拉取请求

📄 许可证

MIT