Plex MCP Server

🚀 Plex MCP 服務器

Plex MCP 服務器是一款基於 模型上下文協議（Model Context Protocol，MCP） 的服務器，它能讓 AI 助手全面訪問你的 Plex 媒體服務器。你可以通過自然語言交互來查詢媒體庫、獲取觀看統計數據，以及管理媒體資源。

🚀 快速開始

前提條件

• Node.js 18 及以上版本
• Plex 媒體服務器（任意較新版本）
• Plex 令牌（獲取 Plex 令牌的方法）
• 支持 MCP 的客戶端（如 Claude Desktop 等）

安裝

# 克隆倉庫
git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server

# 安裝依賴
npm install

# 構建項目
npm run build

配置

1. 獲取你的 Plex 令牌（詳見 下方說明）
2. 創建環境文件：

# 複製示例環境文件
cp .env.example .env

# 編輯文件並填入你的信息
PLEX_URL=http://localhost:32400
PLEX_TOKEN=your_plex_token_here

3. 配置你的 MCP 客戶端： 在 MCP 客戶端配置中添加以下內容（例如 Claude Desktop）：

{
  "mcpServers": {
    "plex": {
      "command": "node",
      "args": ["/path/to/plex-mcp-server/build/index.js"],
      "env": {
        "PLEX_URL": "http://localhost:32400",
        "PLEX_TOKEN": "your_plex_token_here"
      }
    }
  }
}

使用

配置完成後，你可以向 AI 助手提出以下問題：

🎬 "我上週看了哪些電影？"
📺 "給我展示本月最受歡迎的電視劇"
📊 "提供過去 30 天的觀看統計數據"
🔍 "在我的媒體庫中搜索克里斯托弗·諾蘭的電影"
▶️ "我的繼續觀看列表中有什麼？"
📚 "列出我所有的 Plex 媒體庫"

✨ 主要特性

📚 媒體庫管理

• 瀏覽所有 Plex 媒體庫
• 在電影、電視劇、音樂等媒體類型中進行搜索
• 獲取任何媒體項的詳細元數據

📊 類 Tautulli 分析

• 全面的觀看統計數據
• 用戶活動跟蹤
• 熱門內容分析
• 帶有進度跟蹤的觀看歷史記錄
• 媒體庫使用指標

🎯 智能查詢

• 最近觀看的內容
• 已完整觀看的電影/電視劇
• 繼續觀看列表（待播）
• 最近添加的媒體

📦 安裝指南

安裝步驟

# 克隆倉庫
git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server

# 安裝依賴
npm install

# 構建項目
npm run build

💻 使用示例

基礎用法

配置完成後，你可以向 AI 助手提出如下自然語言問題：

🎬 "我上週看了哪些電影？"
📺 "給我展示本月最受歡迎的電視劇"
📊 "提供過去 30 天的觀看統計數據"
🔍 "在我的媒體庫中搜索克里斯托弗·諾蘭的電影"
▶️ "我的繼續觀看列表中有什麼？"
📚 "列出我所有的 Plex 媒體庫"

高級用法

你可以根據具體需求，靈活組合不同的查詢條件，以獲取更精準的信息。例如，結合時間範圍和媒體類型進行查詢：

"過去一週我觀看的動作電影有哪些？"

📚 詳細文檔

🛠️ 可用函數

🔑 獲取你的 Plex 令牌

1. 在瀏覽器中打開 Plex 網頁應用
2. 導航至設置 → 賬戶 → 隱私
3. 點擊底部的“顯示高級選項”
4. 複製你的 Plex 令牌

另一種方法：

• 訪問：http://YOUR_PLEX_IP:32400/web/index.html#!/settings/account
• 查找“Plex 令牌”字段

📁 項目結構

plex-mcp-server/
├── src/
│   └── index.ts          # 主要的 MCP 服務器實現
├── build/                # 編譯後的 JavaScript 輸出
├── package.json          # Node.js 依賴和腳本
├── tsconfig.json         # TypeScript 配置
├── .env.example          # 環境變量模板
├── README.md             # 本文件
└── LICENSE               # MIT 許可證

🔧 開發

腳本

# 開發模式，支持自動重新加載
npm run dev

# 為生產環境構建
npm run build

# 啟動生產服務器
npm start

# 運行測試（如果已實現）
npm test

從源代碼構建

# 克隆並設置項目
git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server
npm install

# 開發模式
npm run dev

🤝 貢獻代碼

歡迎貢獻代碼！請隨時提交拉取請求。對於重大更改，請先打開一個問題，討論你想要進行的更改。

開發指南

1. ** Fork 倉庫**
2. 創建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打開拉取請求

🐛 故障排除

常見問題

• 連接被拒絕：
  • 驗證你的 Plex 服務器是否正在運行
  • 檢查 .env 文件中的 PLEX_URL
  • 確保端口（通常為 32400）正確
• 身份驗證錯誤：
  • 驗證你的 Plex 令牌是否正確
  • 檢查 Plex 設置中的令牌權限
  • 確保令牌未過期
• 空響應：
  • 某些功能需要 Plex Pass
  • 檢查你的媒體庫是否可訪問
  • 驗證媒體是否已掃描且可用
• MCP 客戶端問題：
  • 確保 build/index.js 的路徑正確
  • 檢查 Node.js 是否在系統路徑中
  • 驗證客戶端配置中是否設置了環境變量

獲取幫助

• 📝 打開一個問題
• 💬 查看現有的 討論
• 📖 查看 MCP 文檔

📋 要求

• Node.js 18.0.0 或更高版本
• Plex 媒體服務器（任意較新版本）
• MCP 服務器和 Plex 服務器之間的網絡訪問權限
• 具有適當權限的有效 Plex 令牌

🔒 安全注意事項

• 妥善保管你的 Plex 令牌 - 切勿將其提交到版本控制系統
• 使用環境變量 存儲敏感配置信息
• 在受信任的網絡上運行 - 該服務器直接與 Plex 進行通信
• 定期輪換令牌 - 考慮定期刷新令牌

🔧 技術細節

項目依賴

本項目基於 Node.js 和 TypeScript 構建，使用了一系列開源庫和工具。具體依賴信息可查看 package.json 文件。

實現原理

該 MCP 服務器通過與 Plex 媒體服務器進行交互，將 Plex 媒體庫轉換為可被 AI 助手查詢的數據庫。它接收來自 AI 助手的自然語言查詢，解析查詢意圖，並根據查詢內容從 Plex 媒體服務器中獲取相應的數據。

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

🙏 致謝

• Anthropic 提供了模型上下文協議
• Plex 提供了出色的媒體服務器
• Tautulli 提供了分析靈感
• 開源社區提供了各種庫和工具

🔗 相關項目

• 模型上下文協議 - 本服務器實現的標準
• Claude Desktop - 流行的 MCP 客戶端
• Tautulli - Plex 監控和分析工具
• PlexAPI - Python Plex API 庫

為 Plex 和 AI 社區用心打造 ❤️