Jellyfin MCP 推荐服务器

概述

这是一个MCP服务器，它连接到Jellyfin媒体服务器，并向大型语言模型（LLM）代理提供只读工具/资源，以进行对话式的媒体推荐。

自然地与克劳德聊聊你的媒体库：

*“帮我找一些时长在2小时以内的90年代喜剧片”*
*“我接下来该看什么？”*
*“我想要点黑暗又搞笑的东西”*
*“我的图书馆里有什么新内容？”*

它实现了在（某处）定义的合同 jellyfin-mcp.spec.yaml。

______________________________________________________________________

📖 目录

🚀 开始使用

快速入门 - 选择您的安装方法

- NPX 安装（推荐） - 终端用户，快速测试 - 本地开发环境设置 - 开发者，贡献者 - 安全配置 - 注重安全的用户 - 快速故障排除 - 常见问题及解决方案

🔒 安全与认证

安全最佳实践 - 全面的安全指导

- 核心安全原则 - 关键安全警告 - 安全考虑因素与威胁模型 - 风险评估 - 安全检查清单 - 8项可操作的检查清单 - 令牌管理 - 创建、轮换和存储 - 生产安全 - 企业部署指南 - 安全监控 - 威胁检测和警示信号

🔧 开发与贡献指南

发展与贡献 - 完整的开发者指南

- 快速开发环境搭建 - 5分钟内快速上手 - 开发命令 - 测试、质量、构建 - 项目架构 - 技术基础 - 代码质量标准 - 自动化质量保证 - 开发工作流程 - 持续集成/持续交付（CI/CD）和分支管理 - 贡献指南 - 分步骤贡献流程 - 任务自动化 - 完整的任务参考

📚 参考资料与工具

可用工具 - 媒体和认证工具
文档 - 额外的文档文件

______________________________________________________________________

🚀 快速入门

选择你的道路

🎈 只是想试试看？ → NPX 安装 🔧 本地开发？ → 本地开发环境设置 🔒 需要最高级别的安全吗？ → 安全配置指南

______________________________________________________________________

NPX 安装（推荐）

非常适合： 终端用户，快速测试，生产部署

先决条件：

已安装 Node.js v20+
Jellyfin服务器已运行并可访问
已安装Claude桌面应用程序

设置（2分钟）：

添加到Claude桌面配置中 (claude_desktop_config.json):

   {
     "mcpServers": {
       "jellyfin": {
         "command": "npx",
         "args": ["-y", "jellyfin-suggestion-mcp@latest"],
         "env": {
           "JELLYFIN_BASE_URL": "http://your-jellyfin-server:8096"
         }
       }
     }
   }

重启Claude桌面版 完全地

测试它是否有效： 在新的Claude对话中，尝试：

   "What's in my Jellyfin library?"

在提示时进行身份验证： 当你第一次使用任何工具时，Claude 会显示：

   Error: Authentication required. Please use the authenticate_user tool to sign in, then your request will be automatically retried.

只需告诉克劳德： “请验证我的身份” 并在被询问时提供您的Jellyfin凭据。 接下来会发生什么：

- 克劳德称之为 authenticate_user 使用您的用户名/密码登录工具 - 系统生成一个安全的会话令牌 - 您的原始请求已自动重试 - 您既看到了认证成功的信息，也看到了您请求的数据

🔒 安全提示：

- 凭证永远不会被记录或持久存储 - 在您的Claude对话期间，会话令牌仅存在于内存中 - 每次新的Claude对话都需要重新认证

✅ 成功： 你应该能看到你的图书馆概览，并且能够请求推荐！

❌ 遇到问题了吗？ 跳转到快速故障排除

______________________________________________________________________

本地开发环境设置

非常适合： 开发者、贡献者、定制化、高级配置

先决条件：

已安装 Node.js v20+
Git已安装
Jellyfin 服务器已运行并可访问
已安装Claude桌面应用程序

设置（5分钟）：

克隆并安装：

   git clone https://github.com/PCritchfield/jellyfin-suggestion-mcp.git
   cd jellyfin-suggestion-mcp
   yarn install
   # OR: task install

配置环境：

   cp .env.example .env
   # Edit .env with your Jellyfin server details

选择您的认证方式：

选项A：交互式认证（推荐）

   # .env file - minimal configuration
   JELLYFIN_BASE_URL=http://your-jellyfin-server:8096

当Claude要求时，您将使用用户名/密码进行身份验证。

选项B：环境用户名/密码

   # .env file - username/password authentication
   JELLYFIN_BASE_URL=http://your-jellyfin-server:8096
   JELLYFIN_USERNAME=your-jellyfin-username
   JELLYFIN_PASSWORD=your-jellyfin-password
   JELLYFIN_PROTOCOL=https  # Optional: http or https (defaults to https)

选项C：预配置令牌

   # .env file - token-based authentication
   JELLYFIN_BASE_URL=http://your-jellyfin-server:8096
   JELLYFIN_USER_ID=your-user-id-guid-here
   JELLYFIN_TOKEN=your-api-token-here

如何获取API令牌：

1. 跑 yarn get-users 找到你的用户ID 1. 前往Jellyfin仪表板 → API密钥 1. 创建一个名为“MCP 服务器”的新 API 密钥 1. 将令牌复制到您的 .env 文件

测试连接：

   yarn test:connection
   # OR: task test:connection

预期输出： ✅ Jellyfin connection successful!

认证测试：

   yarn test:auth
   # Verifies both interactive and token-based authentication

添加到Claude桌面配置中：

   {
     "mcpServers": {
       "jellyfin": {
         "command": "node",
         "args": ["--import", "tsx/esm", "/full/path/to/your/project/src/index.ts"],
         "cwd": "/full/path/to/your/project",
         "env": {
           "JELLYFIN_BASE_URL": "http://your-jellyfin-server:8096"
         }
       }
     }
   }

重启Claude桌面版 并使用以下进行测试： "What's in my Jellyfin library?"

🛠️ 开发命令：

task --list          # Show all available tasks
task dev             # Start development server with hot reload
task test            # Run all tests
task lint            # Check code quality

______________________________________________________________________

安全配置

非常适合： 注重安全的用户、共享系统、生产环境

选择您偏好的安全方法：

🔐 环境变量（推荐）：

*对于基于令牌的身份验证：*

# Add to your shell profile (.bashrc, .zshrc, etc.)
export JELLYFIN_BASE_URL="http://your-jellyfin-server:8096"
export JELLYFIN_USER_ID="your-user-id-here"
export JELLYFIN_TOKEN="your-api-token-here"

*对于用户名/密码认证：*

# Username/password environment setup
export JELLYFIN_BASE_URL="your-jellyfin-server:8096"  # Without protocol
export JELLYFIN_USERNAME="your-jellyfin-username"
export JELLYFIN_PASSWORD="your-jellyfin-password"
export JELLYFIN_PROTOCOL="https"  # Optional: http or https (defaults to https)

*对于交互式认证：*

# Minimal environment setup
export JELLYFIN_BASE_URL="http://your-jellyfin-server:8096"
# No credentials needed - authenticate with username/password when prompted

然后使用一个不包含嵌入式凭据的干净Claude配置：

{
  "mcpServers": {
    "jellyfin": {
      "command": "npx",
      "args": ["-y", "jellyfin-suggestion-mcp@latest"]
    }
  }
}

📁 本地配置文件：

# Keep sensitive config separate from shared files
cp claude_desktop_config.json claude_desktop_config.local.json
# Edit local version with credentials, share the example version

🔄 认证方法迁移：

*从基于令牌到交互式：*

移除 JELLYFIN_USER_ID 并且 JELLYFIN_TOKEN 来自环境
仅保留 JELLYFIN_BASE_URL
下次与Claude对话时，将提示输入用户名/密码

*从交互式环境到用户名/密码环境：*

添加 JELLYFIN_USERNAME 并且 JELLYFIN_PASSWORD 对环境
可选设置 JELLYFIN_PROTOCOL 对于HTTP/HTTPS的偏好设置
重启 Claude 桌面版以进行自动认证

*从用户名/密码认证到基于令牌的认证：*

从Jellyfin仪表板→API密钥中获取API令牌
替换 JELLYFIN_USERNAME 并且 JELLYFIN_PASSWORD 和；与；带着；用 JELLYFIN_USER_ID 并且 JELLYFIN_TOKEN
重启Claude桌面版

🔑 API令牌设置：

前往Jellyfin仪表盘 → API密钥
为这个应用程序创建新的API密钥
使用基于令牌的身份验证，而不是交互式身份验证

💡（这个符号在中文里通常被用作表示“灯泡”的意象，或者作为表情符号表示“灵感”、“想法”等，直接翻译可能无法准确传达其含义，但在这里可以简单理解为“灵感来了”或“有想法了”的意思，不过具体翻译需根据上下文确定。） 想要更多安全选项吗？ 看全面安全指南在......下面

______________________________________________________________________

快速故障排除

服务器无法启动？

# Check for errors
yarn build
yarn test:connection

克劳德无法连接？

验证服务器是否正在运行yarn dev 或者 npx （进程）
检查文件路径中的 claude_desktop_config.json 是绝对且正确的
完全重启Claude桌面版
检查Claude Desktop日志中的错误

认证失败？

*连接问题：*

Cannot connect to Jellyfin server at http://...

验证 JELLYFIN_BASE_URL 是正确且可访问的
检查Jellyfin服务器是否正在运行且可访问
确保防火墙/网络设置允许访问

*交互式认证问题：*

Invalid username or password

验证您的Jellyfin凭据是否正确
检查Jellyfin中的用户帐户是否已启用
确保用户有权登录

*令牌认证问题：*

Invalid or expired token

使用交互式方法重新进行身份验证
检查Jellyfin仪表板中API令牌是否未被撤销
验证 JELLYFIN_USER_ID 匹配代币持有者

*用户名/密码环境问题：*

Environment username/password authentication failed

验证 JELLYFIN_USERNAME 并且 JELLYFIN_PASSWORD 是正确的
检查Jellyfin中的用户帐户是否已启用
确保凭据与有效的Jellyfin用户帐户匹配

*协议配置问题：*

Invalid JELLYFIN_PROTOCOL "xyz". Must be "http" or "https"

仅限使用 http 或者 https for JELLYFIN_PROTOCOL 不区分大小写
如果 JELLYFIN_BASE_URL 包括协议在内，它具有优先权
如果未指定协议，则默认使用HTTPS以确保安全

测试您的身份验证：

yarn test:auth  # Tests both interactive and token-based auth
yarn test:connection  # Basic connection test
yarn tsx src/test-auth-env.ts  # Test environment variable authentication priority
yarn tsx src/test-protocol.ts  # Test protocol configuration

↑ 返回顶部

______________________________________________________________________

🔒 安全最佳实践

核心安全原则

⚠️ 致命错误： 您的Jellyfin凭据应该从未致力于版本控制或公开共享。

🛡️ 实施了安全措施：

Gitignore 保护 - 敏感配置文件未纳入版本控制
示例模板 - 提供占位符配置以确保安全共享
环境变量支持 - 服务器从安全环境中读取凭据
会话管理 - 凭据仅在与Claude对话期间存储在内存中
无凭证记录 - 用户名、密码和令牌绝不会被记录

🚨 安全考量与威胁模型

API Token Scope:

Jellyfin API令牌具有 广泛的获取途径 到您的媒体服务器
考虑创建一个 专用只读用户 对于这个应用
令牌可以在授予的权限范围内访问所有媒体和用户数据

网络暴露

如果Jellyfin可在本地网络外部访问，风险会增加
如果将Jellyfin对外暴露，请确保防火墙配置正确
考虑使用VPN访问，而非直接暴露于互联网

凭证存储：

Claude Desktop的配置文件可能包含敏感信息
环境变量比嵌入式凭据更安全
本地配置文件应通过文件权限得到妥善保护

📋 安全检查清单

完成此安全部署检查清单：

\[ \] 凭证管理选择安全的凭证管理方式（推荐使用环境变量）
\[ \] 移除硬编码的凭据提交的配置文件中没有凭证
\[ \] Jellyfin 用户权限审查并最小化用户权限（考虑使用只读用户）
\[ \] 令牌轮换计划安排定期的API令牌轮换
\[ \] 网络安全验证Jellyfin的网络暴露情况和防火墙设置
\[ \] 文件权限为本地配置文件设置适当的权限以确保其安全性
\[ \] 备份安全确保备份中不泄露凭据
\[ \] 团队访问如果要分享，请使用不包含真实凭据的示例配置

🔄 代币管理

创建安全的API令牌：

创建专用用户考虑为MCP访问设置一个只读用户
生成令牌Jellyfin 控制面板 → API 密钥 → 创建新密钥
安全存储存储在环境变量中，而非配置文件中
定期轮换定期更换令牌（建议：每季度一次）

令牌轮换流程：

在Jellyfin仪表板中生成新令牌
更新环境变量或安全配置
使用新令牌进行测试 yarn test:auth
从Jellyfin仪表板中删除旧令牌
重启Claude桌面版以使用新令牌

🏭 生产安全

对于生产环境部署：

使用合适的 密钥管理系统 (HashiCorp Vault、AWS Secrets Manager 等)
实施 令牌轮换自动化
启用 审计日志记录 用于凭据访问
使用 专用服务账户 具有最小权限
实施 网络分段 用于访问媒体服务器

环境特定考量因素：

发展Shell 配置文件中的环境变量
持续集成/持续交付（CI/CD）加密的环境变量或密钥
生产企业机密管理与轮换
共享系统用户特定凭证隔离

🔍 安全监控

需要监控的内容：

认证失败尝试
非典型的API使用模式
来自意外来源的代币使用
与Jellyfin服务器的网络连接

警示信号：

多次认证失败
超出正常使用模式的API调用
来自意外IP地址的连接
从不同地点同时使用的代币

↑ 返回顶部

______________________________________________________________________

可用工具

一旦连接到Claude Desktop，您将能够使用以下Jellyfin工具：

媒体工具

📚 图书馆概览 - 快速概览您的收藏
🔍 搜索项目 - 基于文本和过滤器的搜索
📋 列表项 - 按类别浏览并使用筛选器
📺 下一档节目 - 继续看电视剧
🎯 推荐相似内容 - 基于人工智能的推荐
🎬 流媒体信息 - 播放能力信息

认证工具

🔐 验证用户身份 - 使用用户名/密码登录
🎫 代币集合 - 使用现有的API令牌

示例提示：

*“帮我找一些时长在2小时以内的90年代喜剧片”*
*“我接下来应该看什么？”*
*“我想要点黑暗又搞笑的东西”*
*“我的图书馆里有什么新内容？”*

💡 这个符号通常代表“灯泡”，在中文里可以翻译为“💡 灵感”或者“💡 点子”，用来表示想到了一个好主意或灵感。 需要帮助来开始吗？ 跳转到快速入门用于安装说明。

↑ 返回顶部

______________________________________________________________________

📚 文档

原始文件

README.md - 完整的用户指南 包括安装、认证、安全和开发

- 所有设置程序整合，并逐步披露 - 全面融入最佳安全实践 - 开发工作流程和贡献指南 - 内部导航和交叉引用，便于快速访问

存档文档

以下文件包含原始详细文档，并可供参考：

SETUP.md - *（已存档）* 原始详细设置指南
AUTHENTICATION.md - *（已存档）* 原始认证文件
SECURITY.md - *（已存档）* 最佳原始安全实践
PRD.md - 产品需求文档（技术规格）

移民信息

📋 表格、清单 对于现有用户所有来自存档文件的信息都已整合到本README文件中，并进行了更好的组织和交叉引用。存档文件将继续保留以确保向后兼容，但 此README文件现为主要文档来源。 🔗（这个符号在中文中通常没有直接的翻译，它表示链接或超链接的意思，可以理解为“链接”或“点击这里”等，具体翻译取决于上下文） 外部链接如果您有书签或指向已归档文档文件的外部引用，它们将继续有效，但我们建议更新链接以指向本README文件中的相关部分，以获得最佳体验。

↑ 返回顶部

______________________________________________________________________

🔧 开发与贡献

快速开发环境搭建

先决条件：

已安装 Node.js v20+
Yarn 包管理器
用于测试的Jellyfin服务器

开始：

git clone https://github.com/PCritchfield/jellyfin-suggestion-mcp.git
cd jellyfin-suggestion-mcp
yarn install
task setup              # Complete project setup
task dev                # Start development server with hot reload

______________________________________________________________________

开发命令

🧪 测试与验证：

# Basic testing
yarn test               # Run spec tests
yarn test:connection    # Test Jellyfin connection
yarn test:auth          # Test authentication system
yarn get-users          # List Jellyfin users

# Full validation
task ci                 # Run complete CI pipeline locally
task test:spec          # Run spec acceptance tests

🔍 代码质量：

# Linting and formatting
yarn lint               # Run ESLint
yarn lint:fix           # Fix auto-fixable issues
yarn type-check         # TypeScript type checking
yarn security:audit     # Security audit of dependencies

# Task runner equivalents
task lint               # ESLint with TypeScript support
task lint:fix           # Auto-fix code quality issues
task type-check         # Full TypeScript validation
task audit              # Security and dependency audit

🏗️ 构建与运行：

# Development
task dev                # Development server with hot reload
task build              # Compile TypeScript to JavaScript
task start              # Run compiled production server

# Production
yarn build && yarn start    # Build and run production version

______________________________________________________________________

项目架构

技术基础：

语言带有严格类型检查的TypeScript
平台MCP 1.2+ 协议规范
目标Jellyfin 10.8+ 媒体服务器兼容性
演出在包含≤20,000个项目的库中，≤24个项目响应时间\ 📖（表示一本书的符号，无直接文字含义，可理解为“书”或“书籍”） 完整任务参考见 Taskfile.yml 以获取完整的任务定义和用法

↑ 返回顶部

Jellyfin Suggestion MCP

快速接入

详细介绍

Jellyfin MCP 推荐服务器

概述

📖 目录

🚀 开始使用

🔒 安全与认证

🔧 开发与贡献指南

📚 参考资料与工具

🚀 快速入门

选择你的道路

NPX 安装（推荐）

本地开发环境设置

安全配置

快速故障排除

🔒 安全最佳实践

核心安全原则

🚨 安全考量与威胁模型

📋 安全检查清单

🔄 代币管理

🏭 生产安全

🔍 安全监控

可用工具

媒体工具

认证工具

📚 文档

原始文件

存档文档

移民信息

🔧 开发与贡献

快速开发环境搭建

开发命令

项目架构

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP