杰利芬建议mcp

Name: 杰利芬建议mcp
Author: PCritchfield

作者：PCritchfield3 星标更新：2025-11-17

安装使用来源：spider==github.com

项目介绍

Jellyfin MCP 推荐服务器

概述

这是一个连接到 Jellyfin 媒体服务器并为对话式媒体推荐提供只读工具/资源的 MCP 服务器。

与 Claude 自然地讨论你的媒体库：

"给我找一些90年代的喜剧电影，时长不超过2小时"
"我接下来应该看什么？"
"我想看一些黑暗又有趣的电影"
"我的库中有什么新内容？"

它实现了在 jellyfin-mcp.spec.yaml 中定义的契约。

📖 目录

🚀 快速开始

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

🔒 安全与认证

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

🔧 开发与贡献指南

开发与贡献 - 完整的开发者指南
- 快速开发设置 - 五分钟内开始
- 开发命令 - 测试、质量、构建
- 项目架构 - 技术基础
- 代码质量标准 - 自动化质量保证
- 开发工作流 - CI/CD 和分支策略
- 贡献指南 - 步步为营的贡献过程
- 任务自动化 - 完整的任务参考

📚 参考与工具

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

🚀 快速开始

选择你的路径

🎈 只想试一试？ → NPX 安装 🔧 本地开发？ → 本地开发设置 🔒 需要最大安全性？ → 安全配置指南

NPX 安装（推荐）

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

前提条件：

已安装 Node.js v20+
运行并可访问的 Jellyfin 服务器
已安装的 Claude Desktop 应用

设置（2分钟）：

添加到 Claude Desktop 配置 (claude_desktop_config.json)：

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

完全重启 Claude Desktop
测试是否正常工作： 在新的 Claude 对话中尝试：
```
"我的 Jellyfin 库里有什么？"
```
当提示时进行身份验证： 第一次使用任何工具时，Claude 将显示：
```
错误：需要身份验证。请使用 authenticate_user 工具登录，然后您的请求将自动重试。
```
只需告诉 Claude："请验证我" 并在被询问时提供你的 Jellyfin 凭据。 接下来会发生什么：
- Claude 调用带有用户名/密码的 authenticate_user 工具
- 系统生成一个安全会话令牌
- 自动重试你的原始请求
- 你会看到身份验证成功以及你请求的数据
🔒 安全注意事项：
- 凭据永远不会被记录或持久存储
- 会话令牌仅在你的 Claude 对话期间存在于内存中
- 每个新的 Claude 对话都需要重新进行身份验证

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

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

本地开发设置

适合： 开发者，贡献者，定制，高级配置

前提条件：

已安装 Node.js v2
已安装 Git
运行并可访问的 Jellyfin 服务器
已安装的 Claude Desktop 应用

设置（5分钟）：

克隆并安装：

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

配置环境：

cp .env.example .env
# 编辑 .env 文件以包含你的 Jellyfin 服务器详情

选择你的认证方式：

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

# .env 文件 - 最小配置
JELLYFIN_BASE_URL=http://your-jellyfin-server:8096

当 Claude 提问时，你需要使用用户名/密码进行认证。

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

# .env 文件 - 用户名/密码认证
JELLYFIN_BASE_URL=http://your-jellyfin-server:8096
JELLYFIN_USERNAME=your-jellyfin-username
JELLYFIN_PASSWORD=your-jellyfin-password
JELLYFIN_PROTOCOL=https  # 可选：http 或 https（默认为 https）

选项 C：预配置令牌

# .env 文件 - 基于令牌的认证
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
# 或者：task test:connection

预期输出：✅ Jellyfin 连接成功！

认证测试：

yarn test:auth
# 验证交互式和基于令牌的认证

添加到 Claude Desktop 配置：

{
  "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 Desktop 并测试："我的 Jellyfin 库里有什么？"

🛠️ 开发命令：

task --list          # 显示所有可用任务
task dev             # 启动具有热重载的开发服务器
task test            # 运行所有测试
task lint            # 检查代码质量

安全配置

适合： 关注安全性的用户，共享系统，生产环境

选择你喜欢的安全方法：

🔐 环境变量（推荐）：

对于基于令牌的认证：

# 添加到你的 shell 配置文件（.bashrc, .zshrc 等）
export JELLYFIN_BASE_URL="http://your-jellyfin-server:8096"
export JELLYFIN_USER_ID="your-user-id-here"
export JELLYFIN_TOKEN="your-api-token-here"

对于用户名/密码认证：

# 用户名/密码环境设置
export JELLYFIN_BASE_URL="your-jellyfin-server:8096"  # 不带协议
export JELLYFIN_USERNAME="your-jellyfin-username"
export JELLYFIN_PASSWORD="your-jellyfin-password"
export J
ELLYFIN_PROTOCOL="https"  # 可选：http 或 https（默认为 https）

对于交互式认证：

# 最小环境设置
export JELLYFIN_BASE_URL="http://your-jellyfin-server:8096"
# 不需要凭据 - 当提示时使用用户名/密码进行认证

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

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

📁 本地配置文件：

# 将敏感配置与共享文件分开
cp claude_desktop_config.json claude_desktop_config.local.json
# 编辑本地版本中的凭据，分享示例版本

🔄 认证方法迁移：

从基于令牌到交互式：

从环境中移除 JELLYFIN_USER_ID 和 JELLYFIN_TOKEN
仅保留 JELLYFIN_BASE_URL
下次 Claude 对话时将提示输入用户名/密码

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

在环境中添加 JELLYFIN_USERNAME 和 JELLYFIN_PASSWORD
根据需要设置 JELLYFIN_PROTOCOL 以偏好 HTTP/HTTPS
重启 Claude Desktop 以实现自动认证

从用户名/密码到基于令牌：

从 Jellyfin 仪表板 → API 密钥获取 API 令牌
使用 JELLYFIN_USER_ID 和 JELLYFIN_TOKEN 替换 JELLYFIN_USERNAME 和 JELLYFIN_PASSWORD
重启 Claude Desktop

🔑 API 令牌设置：

转到 Jellyfin 仪表板 → API 密钥
为此应用程序创建新的 API 密钥
使用基于令牌的认证而不是交互式认证

💡 想要更多安全选项？ 请参阅下面的完整安全指南

快速故障排除

服务器无法启动？

# 检查错误
yarn build
yarn test:connection

Claude 无法连接？

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

认证失败？

连接问题：

无法连接到 http://... 的 Jellyfin 服务器

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

交互式认证问题：

无效的用户名或密码

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

基于令牌的认证问题：

无效或过期的令牌

使用交互式方法重新认证
检查 Jellyfin 仪表板中 API 令牌是否未被撤销
验证 JELLYFIN_USER_ID 是否匹配令牌所有者

用户名/密码环境问题：

环境用户名/密码认证失败

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

协议配置问题：

无效的 JELLYFIN_PROTOCOL "xyz"。必须是 "http" 或 "https"

仅使用 http 或 https 作为 JELLYFIN_PROTOCOL（大小写不敏感）
如果 JELLYFIN_BASE_URL 包含协议，则优先级更高
默认情况下，如果未指定协议，则使用 HTTPS 以确保安全

测试你的认证：

yarn test:auth  # 测试交互式和基于令牌的认证
yarn test:connection  # 基本连接测试
yarn tsx src/test-auth-env.ts  # 测试环境变量认证优先级
yarn tsx src/test-protocol.ts  # 测试协议配置

仍然卡住了？ 请参阅上面的快速故障排除或打开一个问题。

↑ 返回顶部

🔒 最佳安全实践

核心安全原则

⚠️ 关键： 你的 Jellyfin 凭据应永远不提交到版本控制或公开分享。

🛡️ 实施的安全措施：

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

🚨 安全考虑与威胁模型

API 令牌范围：

Jellyfin API 令牌对你的媒体服务器有广泛的访问权限
考虑为此应用程序创建一个专用的只读用户
令牌可以访问授予权限内的所有媒体和用户数据

网络暴露：

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

凭据存储：

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

📋 安全检查表

完成此检查表以进行安全部署：

凭据管理：选择安全的凭据方法（推荐使用环境变量）
删除硬编码凭据：配置文件中没有凭据
Jellyfin 用户权限：审查并最小化用户权限（考虑只读用户）
令牌轮换计划：定期安排 API 令牌轮换
网络安全：验证 Jellyfin 网络暴露和防火墙设置
文件权限：使用适当的权限保护本地配置文件
备份安全：确保备份不会暴露凭据
团队访问：如果共享，请使用不含真实凭据的示例配置

🔄 令牌管理

创建安全 API 令牌：

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

令牌轮换流程：

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

🏭 生产安全

对于生产部署：

使用适当的秘密管理系统（如 HashiCorp Vault、AWS Secrets Manager 等）
实现令牌轮换自动化
启用审计日志以记录凭据访问
使用专用服务账户并最小化权限
实现网络分段以访问媒体服务器

特定环境的考虑：

开发：在 shell 配置文件中使用环境变量
CI/CD：加密的环境变量或秘密
生产：企业级秘密管理和轮换
共享系统：用户特定的凭据隔离

🔍 安全监控

监控的内容：

失败的身份验证尝试
异常的 API 使用模式
来自意外来源的令牌使用
到 Jellyfin 服务器的网络连接

警示标志：

多次身份验证失败
超出正常使用模式的 API 调用
来自意外 IP 地址的连接
从不同位置同时