使用说明

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令牌：

跑 yarn get-users 找到你的用户ID
前往Jellyfin仪表板 → API密钥
创建一个名为“MCP 服务器”的新 API 密钥
将令牌复制到您的 .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个项目响应时间<2秒

关键组件：

MCP服务器实现 - 核心服务器遵循MCP规范
Jellyfin 集成 只读API客户端，带认证
规格验证 - 机器可读的 jellyfin-mcp.spec.yaml
测试支架（或测试框架） - 自动化规格验收测试

代码质量标准

自动化质量保证：

ESLint（中文可译为“ES代码检查工具”或保持原名，因其是一个专为JavaScript（尤其是ES6+）设计的代码检查工具） 支持TypeScript并具有严格的规则
提交前钩子（或提交前触发器） 用于提交时的自动化质量检查
约定式提交（或规范提交） 用于标准化的提交信息
语义化发布 用于自动化版本管理和变更日志记录

安全与隐私：

不记录凭证 - 敏感数据从不记录
编辑过的URL - 文件路径和流URL默认被隐去
儿童模式的尊重 - 强化儿童安全政策
令牌验证 所有API令牌在使用前均已验证

开发工作流程

包管理：

纱线作为主要的包管理器，采用基于锁文件的依赖管理
安全审计 集成到CI/CD流水线中
自动依赖更新 通过 Dependabot

分支策略：

基于主干的开发 和；与；带着 main 分支
所有工作流程 在推送/拉取请求（PR）时运行 main 分支
安全扫描 每周按计划运行
无破坏性变更 无需进行主要版本升级

持续集成/持续交付（CI/CD）流水线：

持续集成流水线（CI Pipeline） - 代码格式化检查、类型检查和测试
代码质量 - 高级代码分析和文档检查
安全扫描 - 依赖项漏洞、秘密扫描和安全分析
发布自动化 - 语义化版本发布和自动化发布

贡献指南

如何贡献：

分叉和克隆：

git clone https://github.com/YOUR_USERNAME/jellyfin-suggestion-mcp.git
cd jellyfin-suggestion-mcp

设置开发环境：

yarn install
task setup
task test:connection    # Verify your Jellyfin connection

创建特性分支：

git checkout -b feature/your-feature-name

做出改变：
- 遵循现有的代码风格和TypeScript模式
- 为新功能添加测试
- 根据需要更新文档
- 确保所有质量检查均通过： task ci

提交更改：

git add .
git commit -m "feat: add your feature description"
# Follow conventional commit format

提交拉取请求：
- 确保所有持续集成（CI）检查都通过
- 包含对变更的清晰描述
- 提及任何相关问题

贡献标准：

代码覆盖率保持或提高测试覆盖率
规格合规性所有规格验收测试必须通过
文档更新面向用户的任何变更的相关文档
兼容性保持向后兼容性，除非是主要版本更新
演出确保更改不会导致响应时间下降

贡献成功的衡量标准：

在持续集成（CI）中，100%的规格测试通过
基于大型语言模型（LLM）的媒体请求95%以上的时间返回有效结果
在所有相关通话中强制实施儿童模式和结果限制
在未增加主版本号的情况下，不进行破坏性变更

任务自动化

可用命令：

task --list              # Show all available tasks
task setup               # Complete project setup
task dev                 # Start development server
task test                # Run all tests
task lint                # Code quality checks
task build               # Build for production
task ci                  # Full CI pipeline locally

任务类别：

设置与安装 - 项目初始化和依赖项
发展 - 实时开发服务器和热重载
测试 - 单元测试、集成测试和规范验证
质量 - 代码规范检查、类型检查和安全审计
建筑 - TypeScript 编译和生产构建
维护 - 依赖项更新和清理

📖（表示一本书的符号，无直接文字含义，可理解为“书”或“书籍”） 完整任务参考见 Taskfile.yml 以获取完整的任务定义和用法

↑ 返回顶部

使用说明

Jellyfin MCP 推荐服务器

概述

📖 目录

🚀 开始使用

🔒 安全与认证

🔧 开发与贡献指南

📚 参考资料与工具

🚀 快速入门

选择你的道路

NPX 安装（推荐）

本地开发环境设置

安全配置

快速故障排除

🔒 安全最佳实践

核心安全原则

🚨 安全考量与威胁模型

📋 安全检查清单

🔄 代币管理

🏭 生产安全

🔍 安全监控

可用工具

媒体工具

认证工具

📚 文档

原始文件

存档文档

移民信息

🔧 开发与贡献

快速开发环境搭建

开发命令

项目架构

代码质量标准

开发工作流程

贡献指南

任务自动化

相关 MCP

OpenAPI工具服务器

威胁情报服务器

FastMCP文档服务器扩展

食谱助手

TRIZ 9窗口分析服务器

SQLite记忆库服务