Overseerr MCP

这是一个为Overseerr设计的模型上下文协议（MCP）集成，它通过Claude AI使您能够以自然语言与您的媒体请求系统进行交互。该服务器允许您搜索电影和电视剧，提出媒体请求，并使用对话语言管理您的Overseerr实例。

示例对话

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

You: Can you find any recent sci-fi movies?
Claude: Let me search for recent science fiction films...
[Uses overseerr:search to find recent sci-fi movies]

You: That looks good! Can you request the second one?
Claude: I'll request that movie for you...
[Uses overseerr:request to submit the media request]

You: What TV shows are available about cooking?
Claude: I'll search for cooking-related TV shows...
[Uses overseerr:search with type='tv' to find cooking shows]

功能

媒体搜索

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

媒体请求

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

集成

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

设置

先决条件

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

快速开始

1. 安装依赖项：

pnpm install

1. 构建项目：

pnpm build

1. 配置环境：

# Copy template
cp .env.template .env

# Edit .env with your values
OVERSEERR_URL=your_overseerr_url
OVERSEERR_API_KEY=your_api_key

1. 配置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"
    }
  }
}

1. 启动服务器：

pnpm start

技术细节

项目结构

packages/
├── config/      # Configuration management
├── overseerr/   # Overseerr API client
├── server/      # MCP server implementation
└── shared/      # Shared types and utilities

可用工具

搜索媒体 (overseerr:search)

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

{
  // The search query - can be a title, person, or general description
  query: string,
  
  // Optional: Filter by type
  // - 'movie': Only search movies
  // - 'tv': Only search TV shows
  // - 'person': Only search people
  type?: 'movie' | 'tv' | 'person'
}

示例查询：

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

请求媒体 (overseerr:request)

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

{
  // The TMDB ID of the media to request
  mediaId: number,
  
  // Type of media being requested
  // - 'movie': Request a movie
  // - 'tv': Request a TV show
  mediaType: 'movie' | 'tv',
  
  // Optional: For TV shows, specify which seasons to request
  // If not provided, requests all available seasons
  seasons?: number[]
}

示例请求：

• 请求一部电影：“请求《黑客帝国》”
• 请求特定季度：“添加《办公室》第1至3季”
• 请求全部季度：“请求完整的《绝命毒师》系列”

配置

环境变量

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

错误处理

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

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

贡献

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

许可证

MIT