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