内容
<p align="center">
<img src="docs/assets/jellyctl-banner.jpg" alt="jellyctl banner" width="900">
</p>
<h1 align="center">jellyctl</h1>
<p align="center"><strong>适用于 Jellyfin 的操作员控制 CLI，内置 MCP 兼容性。</strong></p>
<p align="center">
<a href="https://lidless.dev/jellyfin-mcp"><strong>网站</strong></a>
·
<a href="https://www.npmjs.com/package/jellyfin-mcp">npm</a>
·
<a href="#install">安装</a>
·
<a href="#cli">CLI</a>
·
<a href="#tools">工具</a>
</p>
<p align="center">
<img src="https://img.shields.io/npm/v/jellyfin-mcp?style=for-the-badge&logo=npm&label=npm" alt="npm 版本">
<img src="https://img.shields.io/github/actions/workflow/status/lidless-labs/jellyctl/ci.yml?branch=main&style=for-the-badge&label=ci" alt="CI 状态">
<img src="https://img.shields.io/badge/MCP-server-8A2BE2?style=for-the-badge" alt="MCP 服务器">
<img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT 许可证">
</p>
jellyctl 是 [Jellyfin](https://jellyfin.org) 的操作员控制 CLI，它为检查和操作 Jellyfin 服务器提供了一个键入的命令界面，而无需点击仪表盘。同一个 npm 包仍然以 `jellyfin-mcp` 的形式发布以保持兼容性，MCP 适配器仍然可以通过 `jellyctl mcp` 和旧的 `jellyfin-mcp` 二进制文件获得。
你想要它，因为询问“客厅里正在播放什么？”或运行 `jellyctl sessions --active-only` 比仪表盘跳转更快，并且因为代理可以通过 MCP 启动这些步骤。与通用 HTTP 工具或手写的脚本相比，MCP 适配器公开了 56 个模式验证的工具，每个破坏性操作都有 `confirm: true` 门控和允许客户端将这些调用路由到人为批准的注释。
> **状态：工作中。** 每天与真实的 Jellyfin 服务器一起使用，但工具界面仍在稳定中，破坏性更改可能会在小版本之间发生。如果您需要稳定性，请固定已发布的版本。
与 [arr-cli](https://github.com/lidless-labs/arr-cli)（*arr stack CLI*）配套。 arr-cli 处理获取内容；jellyctl 处理服务、监控和 Jellyfin 操作。
## 它做什么
Jellyfin 是一个免费的、自托管的媒体服务器：您的电影、节目、音乐和照片都存储在您控制的硬件上。 jellyctl 将媒体服务器的管理界面置于操作员面前：列出会话、检查库、查询用户、搜索项目、查看活动以及从命令行脚本例行检查。对于 MCP 兼容的客户端，`jellyctl mcp` 以 stdio MCP 服务器的形式公开同一个项目，带有 56 个键入的工具，以便代理可以列出谁正在观看什么、暂停或投射会话、扫描库、管理用户、修剪继续观看、运行计划任务或向客户端发送消息，所有这些都是结构化的工具调用，而不是原始的 REST。MCP 界面是可读写的：发现和报告工具是只读的，而每个破坏性或特权操作都位于显式的 `confirm: true` 标志和 `destructiveHint` 注释后面。`jellyfin-mcp` 命令仍然作为兼容性二进制文件支持。
## 安装
```bash
npm install -g jellyfin-mcp
```
这同时安装了 `jellyctl` 和兼容性 `jellyfin-mcp` MCP 二进制文件。
或者从源代码安装：
```bash
git clone https://github.com/lidless-labs/jellyctl.git
cd jellyctl
npm install
npm run build
```
## 快速开始
设置您的 Jellyfin 连接详细信息，然后运行 CLI 命令：
```bash
export JELLYFIN_URL=http://192.0.2.10:8096
export JELLYFIN_API_KEY=your-api-key-here
jellyctl status
jellyctl sessions --active-only
```
对于 MCP 客户端，使用 `jellyctl mcp` 启动适配器或继续使用兼容性 `jellyfin-mcp` 二进制文件。无需全局安装 MCP 路径；`npx` 会获取并运行已发布的 `jellyfin-mcp` 包：
```json
{
"mcpServers": {
"jellyfin": {
"command": "npx",
"args": ["-y", "jellyfin-mcp"],
"env": {
"JELLYFIN_URL": "http://192.0.2.10:8096",
"JELLYFIN_API_KEY": "your-api-key-here"
}
}
}
}
```
然后询问您的代理：*“Jellyfin 现在正在播放什么？”* 它将调用 `jellyfin_list_sessions` 并报告回来。
## 工具
### 系统
- `jellyfin_get_status` - 服务器名称、版本、操作系统、待重启、更新可用性
- `jellyfin_restart_server` - 重启 Jellyfin 进程 *(需要 `confirm: true`)*
- `jellyfin_shutdown_server` - 停止 Jellyfin 进程 *(需要 `confirm: true`)*
### 库
- `jellyfin_list_libraries` - 所有虚拟文件夹，带有 ID、集合类型、路径
- `jellyfin_scan_library` - 触发一个库或所有库的扫描
### 用户
- `jellyfin_list_users` - 带有管理员/禁用标志和最后登录时间戳
- `jellyfin_create_user`
- `jellyfin_delete_user` *(需要 `confirm: true`)*
- `jellyfin_set_user_disabled`
- `jellyfin_set_user_password` *(需要 `confirm: true`)*
> **警告：** `jellyfin_set_user_password` 以纯文本工具输入的形式接受新密码。这意味着密码会传输到您的 LLM 对话、模型提供商的请求日志和任何保存的会话记录中。以这种方式设置的任何密码都视为公开：使用一次性值并让用户在 Jellyfin UI 中更改它，或者在 Jellyfin 仪表盘中设置密码。
### 会话和播放
- `jellyfin_list_sessions` - 活动/空闲客户端，带有当前播放、进度、暂停状态
- `jellyfin_pause_session`
- `jellyfin_resume_session`
- `jellyfin_stop_session`
- `jellyfin_send_message_to_session` - 客户端上的 toast/dialog
- `jellyfin_seek_session` - 跳转到秒数位置
- `jellyfin_next_track` / `jellyfin_previous_track`
- `jellyfin_set_volume` (0-100) / `jellyfin_set_mute` (mute/unmute/toggle)
- `jellyfin_set_audio_stream` / `jellyfin_set_subtitle_stream` （使用 -1 禁用字幕）
- `jellyfin_play_on_session` - 将一个或多个项目投射到会话中（PlayNow / PlayNext / PlayLast）
- `jellyfin_pause_all_sessions` - 暂停匹配的会话 *(需要 `confirm: true`)*
- `jellyfin_stop_all_sessions` - 停止匹配的会话 *(需要 `confirm: true`)*
- `jellyfin_message_all_active_sessions` - 消息匹配的活动会话 *(需要 `confirm: true`)*
### 用户数据
- `jellyfin_mark_played` / `jellyfin_mark_unplayed`
- `jellyfin_set_favorite` / `jellyfin_unset_favorite`
- `jellyfin_preview_continue_watching_clear` - 使用可选筛选器进行 Continue Watching 清理的预演
- `jellyfin_clear_continue_watching` - 清除所选项目的恢复位置或过滤后的 Continue Watching 队列 *(需要 `confirm: true`)*
- `jellyfin_clear_series_continue_watching` - 清除一个节目的恢复位置 *(需要 `confirm: true`)*
- `jellyfin_clear_episode_continue_watching_except_latest` - 保留一个剧集恢复条目并清除一个节目的较旧条目 *(需要 `confirm: true`)*
- `jellyfin_get_watch_history` - 用户最近观看的项目
- `jellyfin_get_user_item_data` - 用户的原始观看/收藏/恢复数据
- `jellyfin_set_resume_position` - 为用户设置项目的恢复位置 *(需要 `confirm: true`)*
### 播放列表
- `jellyfin_list_playlists`
- `jellyfin_create_playlist`
- `jellyfin_get_playlist_items` - 返回 `playlistEntryId` （使用此 ID 删除，而不是原始项目 ID）
- `jellyfin_add_to_playlist`
- `jellyfin_remove_from_playlist`
### 集合
- `jellyfin_create_collection`
- `jellyfin_add_to_collection`
- `jellyfin_remove_from_collection`
### 项目
- `jellyfin_search_items` - 按名称，可选类型筛选
- `jellyfin_get_recent_items` - 最新添加的（按用户）
- `jellyfin_get_item` - 完整的元数据
### 发现
- `jellyfin_get_resume_items` - 用户的进行中的播放，带有秒数恢复位置
- `jellyfin_get_next_up` - 用户的下一个未观看的剧集；可选 `seriesId` 筛选
- `jellyfin_get_similar_items` - Jellyfin 内置的给定项目的“相似”推荐
### 快速连接
- `jellyfin_quick_connect_status` - 服务器上是否启用了快速连接
- `jellyfin_quick_connect_authorize` - 为用户授权待处理代码 *(需要 `confirm: true`)*
### 任务和活动
- `jellyfin_list_scheduled_tasks`
- `jellyfin_run_scheduled_task`
- `jellyfin_get_activity_log`
## CLI
`jellyctl` 是 shell、cron 和 CI 的主要操作员界面。它与 MCP 适配器共享 `JellyfinClient` 核心，并读取相同的 env 配置。当前的 CLI 公开读取/报告/查找命令；播放控制、用户管理和库扫描等写入操作保留在 `confirm: true` 门控后面的 MCP 表面。
```bash
npx jellyfin-mcp@latest status
# 或全局安装：
jellyctl status # 服务器信息；如果无法访问则退出 1
jellyctl libraries
jellyctl users
jellyctl sessions --active-only
jellyctl search "blade runner" --type Movie --limit 5
jellyctl item 6e0b... # 一个项目的完整元数据
jellyctl recent --user 3f1c... --limit 10
jellyctl resume --user 3f1c... # Continue Watching，带有恢复位置
jellyctl next-up --user 3f1c... --series 9a2d...
jellyctl similar 6e0b... --user 3f1c...
jellyctl history --user 3f1c... --type Movie,Episode
jellyctl user-data --user 3f1c... --item 6e0b...
jellyctl activity --limit 50
jellyctl tasks
jellyctl playlists --user 3f1c...
jellyctl playlist 4c7e... --user 3f1c...
jellyctl status --json # 原始 JSON 用于管道
```
运行 `jellyctl help` 以获取完整的命令和标志列表。 `--json` 发出原始 JSON 而不是简洁的人类可读摘要。CLI 读取 `JELLYFIN_URL`、`JELLYFIN_API_KEY`、`JELLYFIN_TIMEOUT` 和 `JELLYFIN_VERIFY_SSL`（参见 [配置](#configuration)）；例如：
```bash
export JELLYFIN_URL=http://192.0.2.10:8096
export JELLYFIN_API_KEY=your-api-key-here
jellyctl status
```
退出代码：`0` 成功，`1` 运行时错误（后端无法访问/调用失败，以及 `status` 当服务器报告无版本时），`2` 用法错误（未知命令/标志或错误值）。
### 启动 MCP 适配器
`jellyctl mcp` 启动 stdio MCP 适配器。兼容的 `jellyfin-mcp` 二进制文件执行相同的操作，仍然支持。直接指向 `dist/index.js` 的启动器继续工作；新的启动器可以指向 `dist/mcp-bin.js`（或 `dist/cli.js mcp`）。使用 `jellyfin-mcp` 二进制名称的启动器不需要更改。
## 配置
在 MCP 客户端配置中设置以下环境变量：
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `JELLYFIN_URL` | 是 | 无 | 基本 URL，例如 `http://localhost:8096` 或 `https://jellyfin.example.com` |
| `JELLYFIN_API_KEY` | 是 | 无 | Jellyfin 仪表盘 > API 密钥中的 API 密钥 |
| `JELLYFIN_TIMEOUT` | 否 | `30` | 请求超时（秒） |
| `JELLYFIN_VERIFY_SSL` | 否 | `true` | 将其设置为 `false` 以跳过 Jellyfin 连接的 TLS 证书验证（例如自签名证书） |
> **注意：** `JELLYFIN_VERIFY_SSL=false` 仅放松 Jellyfin 连接本身的证书验证（通过一个受限的每个请求 HTTP 调度器）。它不会影响进程中其他出站请求的全局 TLS 设置，因此不会影响任何其他出站请求的证书验证。 除非您特别需要它，否则保持安全的默认值。
### 获取 API 密钥
1. 以管理员身份登录 Jellyfin
2. 仪表盘 > API 密钥 > `+`
3. 命名它（例如 `mcp`）并保存
4. 复制值
### Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"jellyfin": {
"command": "jellyfin-mcp",
"env": {
"JELLYFIN_URL": "http://localhost:8096",
"JELLYFIN_API_KEY": "your-api-key-here"
}
}
}
}
```
### Claude 代码
```bash
claude mcp add jellyfin \
--env JELLYFIN_URL=http://localhost:8096 \
--env JELLYFIN_API_KEY=your-api-key-here \
-- jellyfin-mcp
```
添加 `--scope user` 以使其可从任何目录使用而不仅仅是当前项目。
### OpenClaw
如果您从源代码检出运行，请指向已构建的 `dist/index.js`:
```bash
openclaw mcp set jellyfin '{
"command": "node",
"args": ["/absolute/path/to/jellyfin-mcp/dist/index.js"],
"env": {
"JELLYFIN_URL": "http://localhost:8096",
"JELLYFIN_API_KEY": "your-api-key-here"
}'
```
或全局 npm 安装：
```bash
openclaw mcp set jellyfin '{
"command": "jellyfin-mcp",
"env": {
"JELLYFIN_URL": "http://localhost:8096",
"JELLYFIN_API_KEY": "your-api-key-here"
}'
```
然后重启 OpenClaw 网关以获取新的服务器：
```bash
systemctl --user restart openclaw-gateway
openclaw mcp list # 确认“jellyfin” 已注册
```
### Hermes Agent
[Hermes Agent](https://github.com/NousResearch/hermes-agent) 从 `~/.hermes/config.yaml` 读取 MCP 配置，在 `mcp_servers` 键下。添加一个条目：
```yaml
mcp_servers:
jellyfin:
command: "jellyfin-mcp"
env:
JELLYFIN_URL: "http://localhost:8096"
JELLYFIN_API_KEY: "your-api-key-here"
```
或，当从源代码检出运行：
```yaml
mcp_servers:
jellyfin:
command: "node"
args: ["/absolute/path/to/jellyfin-mcp/dist/index.js"]
env:
JELLYFIN_URL: "http://localhost:8096",
JELLYFIN_API_KEY": "your-api-key-here"
```
然后在 Hermes 会话内重新加载 MCP：
```
/reload-mcp
```
### Codex CLI
[Codex CLI](https://github.com/openai/codex) 通过 `codex mcp add` 注册 MCP 服务器：
```bash
codex mcp add jellyfin \
--env JELLYFIN_URL=http://localhost:8096 \
--env JELLYFIN_API_KEY=your-api-key-here \
-- jellyfin-mcp
```
或从源代码检出：
```bash
codex mcp add jellyfin \
--env JELLYFIN_URL=http://localhost:8096 \
--env JELLYFIN_API_KEY=your-api-key-here \
-- node /absolute/path/to/jellyfin-mcp/dist/index.js
```
Codex 将条目写入 `~/.codex/config.toml` 下的 `[mcp_servers.jellyfin]`。使用以下命令进行验证：
```bash
codex mcp list
```
### 通过 SSH 隧道访问远程 Jellyfin
如果 Jellyfin 在远程主机上绑定到 `localhost`（Windows 媒体服务器上常见），请在启动 MCP 客户端之前转发端口：
```bash
ssh -N -L 8096:localhost:8096 mediaserver
```
然后将 `JELLYFIN_URL` 指向 `http://localhost:8096`。MCP 本身没有 SSH 逻辑，它只会讲 HTTP。
## 特性
- `jellyctl` CLI 用于操作员状态、库、用户、会话、项目、活动、任务、播放列表、历史和用户数据检查
- 通过 `jellyctl mcp` 和兼容的 `jellyfin-mcp` 二进制文件进行 MCP 适配器
- **56 个 MCP 工具**，涵盖系统信息、库、用户、会话、项目、计划任务、用户数据写入、播放列表、集合、发现和快速连接
- 播放控制：暂停/恢复/停止/跳转/下一个/上一个/音量/静音/音频流/字幕流/投射（远程播放）/ 发送消息/批量会话控制
- 用户数据写入：标记为已观看/未观看、添加/删除收藏、预览或清除 Continue Watching 恢复位置、设置恢复位置
- 播放列表：创建、列出、追加、删除条目
- 集合：创建、添加、删除
- 发现：恢复队列、下一个剧集、类似项目
- 快速连接：检查状态、为用户授权待处理代码
- 库扫描触发（每个库或所有库）
- 用户管理：列出、创建、删除、启用/禁用、重置密码
- 活动日志查询最近的事件
- 破坏性/特权操作（`restart`、`shutdown`、`delete_user`、`set_user_password`、`quick_connect_authorize`、`jellyfin_clear_continue_watching`、批量会话控制、恢复位置写入）需要显式的 `confirm: true`
- 上游 Jellyfin 错误响应被总结（仅限状态），然后返回给客户端；完整的响应正文会记录到 stderr 中，供操作员使用，因此不会将内部服务器详细信息公开给模型
- 从 shell、cron、CI、Claude Desktop、Claude Code、OpenClaw、Hermes Agent、Codex CLI 和任何 MCP 兼容的客户端工作
## 示例提示
> 我想知道Jellyfin上现在正在播放什么？
调用 `jellyfin_list_sessions` 并设置 `activeOnly=true`。
> 暂停客厅里的播放内容
调用 `jellyfin_list_sessions`，通过设备名称找到会话，然后调用 `jellyfin_pause_session`。
> 扫描电影库
调用 `jellyfin_list_libraries` 来查找ID，然后调用 `jellyfin_scan_library`。
> 给我伴侣的Jellyfin发送消息，告诉他们晚餐准备好了
调用 `jellyfin_list_sessions` -> 通过用户名选择 -> 调用 `jellyfin_send_message_to_session`。
> 最近有哪些计划任务失败了？
调用 `jellyfin_list_scheduled_tasks` 并按 `lastStatus` 筛选。
> 昨晚我正在看什么？
调用 `jellyfin_get_resume_items`，并使用用户ID。返回正在播放的剧集/电影及其续播位置（以秒为单位）。
> 清除该用户的“继续观看”列表。
调用 `jellyfin_list_users` 以解析目标用户，然后调用 `jellyfin_clear_continue_watching` 并设置 `userId` 和 `confirm: true`。
> 显示该剧的“继续观看”列表中将清除哪些内容。
调用 `jellyfin_preview_continue_watching_clear` 并设置 `seriesId` 在进行更改之前。
> 我打开了一堆剧集。保留最新的并清除其余的。
调用 `jellyfin_clear_episode_continue_watching_except_latest` 并设置 `seriesId`、`userId` 和 `confirm: true`。
> 将这部电影的续播时间设置为42分钟。
调用 `jellyfin_set_resume_position` 并设置 `positionSec=2520` 和 `confirm: true`。
> 对我来说，这部剧的下一集是什么？
调用 `jellyfin_get_next_up` 并使用用户ID，可选地使用 `seriesId` 进行筛选。
> 批准我的手机的Jellyfin登录。验证码是 `ABCDEF`。
调用 `jellyfin_list_users` 以解析目标用户，然后调用 `jellyfin_quick_connect_authorize` 并设置 `code`、`userId` 和 `confirm: true`。
## 为什么不选择其他替代方案？
- **为什么不直接从通用HTTP工具调用Jellyfin REST API？** 你可以这样做，但调用者必须知道端点结构、构建查询字符串，并手动处理分页和ID。jellyctl 将有用的读取和报告操作封装为稳定的CLI命令，其MCP适配器公开了56种命名、模式验证的工具，并附有描述，因此模型可以选择 `jellyfin_pause_session` 而不是猜测 `POST /Sessions/{id}/Playing/Pause`。它还会在错误信息和快速连接代码到达模型之前进行编辑。
- **为什么不用shell脚本或几个curl别名？** 脚本适用于一个固定的任务。jellyctl 为操作员提供了一个可重用的命令界面，而MCP适配器允许代理执行其预先未编程的步骤（例如“查找客厅会话，查看正在播放的内容，暂停它，然后给我的伴侣发送消息”），并在Claude Desktop、Claude Code、Codex CLI、OpenClaw和任何其他MCP客户端中重用相同的工具。
- **为什么不用Jellyfin网页控制台？** 网页控制台适用于人类点击。jellyctl适用于通过命令、自然语言和更大工作流与其他工具一起操作的操作员和代理。
## jellyctl是什么
- **不是Jellyfin客户端或播放器。** 它不流式传输、转码或渲染媒体。它通过HTTP控制和查询现有的Jellyfin服务器；播放在您的真实Jellyfin客户端上进行。
- **不是内容获取工具。** 下载、导入或组织文件超出了其范围。与 [arr-cli](https://github.com/lidless-labs/arr-cli) 结合使用以获取内容。
- **本身不是安全边界。** `confirm: true` 门控和MCP `destructiveHint` 注释帮助客户端将风险调用路由到人为批准，但任何具有有效 `JELLYFIN_API_KEY` 的人都可以按照该密钥允许的范围进行操作。请限制API密钥的范围，并保持 `JELLYFIN_VERIFY_SSL` 在其安全默认值。
- **不是托管服务。** 没有SaaS，没有遥测，也没有超出您配置的Jellyfin服务器的网络出口。它作为stdio MCP服务器本地运行。
## 开发
```bash
npm install
npm run dev # 监视模式，带tsx
npm run typecheck # tsc --noEmit
npm run build # tsup bundle
npm test # vitest
```
## 贡献
问题和拉取请求均欢迎。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解工具的结构以及哪些内容可以轻松落地，[SECURITY.md](SECURITY.md) 了解私密报告漏洞，[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 了解行为准则。
## 许可证
[MIT](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器