内容
<p align="center">
<img src="docs/assets/jellyctrl-banner.jpg" alt="jellyctrl banner" width="900">
</p>
<h1 align="center">jellyctrl</h1>
<p align="center"><strong>适用于 Jellyfin 的操作员控制命令行界面，内置 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">命令行界面</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/jellyctrl/ci.yml?branch=main&style=for-the-badge&label=ci" alt="持续集成状态">
<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>
jellyctrl 是一个适用于 [Jellyfin](https://jellyfin.org) 的操作员控制命令行界面，这是一个免费的自托管媒体服务器。它为操作员提供了一个键入的命令界面，用于检查和操作 Jellyfin 服务器，而无需通过仪表盘进行点击。相同的 npm 包仍以 `jellyfin-mcp` 发布以保持兼容，MCP 适配器仍然可以通过 `jellyctrl mcp` 和旧版 `jellyfin-mcp` 二进制文件获得。
您需要它，因为询问“客厅里正在播放什么？”或运行 `jellyctrl sessions --active-only` 比跳转到仪表盘更快，并且因为代理可以通过 MCP 启动这些步骤。与通用 HTTP 工具或手写的脚本相比，MCP 适配器公开了 56 个模式验证的工具，每个破坏性操作都有 `confirm: true` 门控和注释，允许客户端将这些调用路由到人工审批。
> **状态：工作中。** 每天都在一个真实的 Jellyfin 服务器上使用，但工具界面仍在完善中，破坏性更改可能会在小版本之间发生。如果您需要稳定性，请固定一个已发布的版本。
与 [arr-cli](https://github.com/lidless-labs/arr-cli) （*arr stack 命令行界面*）配套。arr-cli 处理内容获取；jellyctrl 处理服务、监控和 Jellyfin 操作。
## 功能
- `jellyctrl` 命令行界面，用于操作员状态、库、用户、会话、项目、活动、任务、播放列表、历史和用户数据检查
- 通过 `jellyctrl mcp` 和兼容的 `jellyfin-mcp` 二进制文件的 MCP 适配器
- **56 个 MCP 工具**，涵盖系统信息、库、用户、会话、项目、计划任务、用户数据写入、播放列表、收藏、发现和快速连接
- 播放控制：暂停 / 恢复 / 停止 / 跳转 / 下一曲 / 上一曲 / 音量 / 静音 / 音频流 / 字幕流 / 投射（远程播放）/ 发送消息 / 批量会话控制
- 用户数据写入：标记为已观看/未观看、添加/删除收藏、预览或清除继续观看的恢复位置、设置恢复位置
- 播放列表：创建、列出、追加、删除条目
- 收藏：创建、添加、删除
- 发现：恢复队列、下一个剧集、类似项目
- 快速连接：检查状态、授权用户的待定代码
- 库扫描触发（每个库或全部）
- 用户管理：列出、创建、删除、启用/禁用、重置密码
- 最近事件的活动日志查询
- 破坏性/特权操作（`restart`、`shutdown`、`delete_user`、`set_user_password`、`quick_connect_authorize`、`jellyfin_clear_continue_watching`、批量会话控制、恢复位置写入）需要明确的 `confirm: true`
- 上游 Jellyfin 错误响应在返回给客户端之前会进行总结（仅状态）；完整响应正文会记录到标准错误输出中，供操作员使用，以便内部服务器详细信息不会被模型公开
- 支持 shell、cron、CI、Claude Desktop、Claude Code、OpenClaw、Hermes Agent、Codex CLI 和任何 MCP 兼容客户端
## 安装
```bash
npm install -g jellyfin-mcp
```
这同时安装了 `jellyctrl` 和兼容的 `jellyfin-mcp` MCP 二进制文件。
或者，从源代码构建：
```bash
git clone https://github.com/lidless-labs/jellyctrl.git
cd jellyctrl
npm install
npm run build
```
## 快速入门
设置 Jellyfin 连接详细信息，然后运行命令行命令：
```bash
export JELLYFIN_URL=http://192.0.2.10:8096
export JELLYFIN_API_KEY=your-api-key-here
jellyctrl status
jellyctrl sessions --active-only
```
对于 MCP 客户端，使用 `jellyctrl 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` - 使用可选筛选器预演继续观看清理
- `jellyfin_clear_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`
## 命令行界面
`jellyctrl` 是用于 shell、cron 和 CI 的主要操作员界面。它与 MCP 适配器共享 `JellyfinClient` 核心，并读取相同的环境变量配置。当前的命令行界面公开了读取/报告/查找命令；播放控制、用户管理、库扫描和其他写入操作保留在 `confirm: true` 门控后面的 MCP 表面。
```bash
npx jellyfin-mcp@latest status
# 或全局安装：
jellyctrl status # 服务器信息；如果无法访问则退出 1
jellyctrl libraries
jellyctrl users
jellyctrl sessions --active-only
jellyctrl search "blade runner" --type Movie --limit 5
jellyctrl item 6e0b... # 一个项目的完整元数据
jellyctrl recent --user 3f1c... --limit 10
jellyctrl resume --user 3f1c... # 继续观看，包含恢复位置
jellyctrl next-up --user 3f1c... --series 9a2d...
jellyctrl similar 6e0b... --user 3f1c...
jellyctrl history --user 3f1c... --type Movie,Episode
jellyctrl user-data --user 3f1c... --item 6e0b...
jellyctrl activity --limit 50
jellyctrl tasks
jellyctrl playlists --user 3f1c...
jellyctrl playlist 4c7e... --user 3f1c...
jellyctrl status --json # 原始 JSON，用于管道传输
```
运行 `jellyctrl help` 获取完整的命令和标志列表。`--json` 发出原始 JSON 而不是简洁的人类可读摘要。命令行界面读取 `JELLYFIN_URL`、`JELLYFIN_API_KEY`、`JELLYFIN_TIMEOUT` 和 `JELLYFIN_VERIFY_SSL` （参见 [配置](#配置)）；例如：
```bash
export JELLYFIN_URL=http://192.0.2.10:8096
export JELLYFIN_API_KEY=your-api-key-here
jellyctrl status
```
退出代码：`0` 成功，`1` 运行时错误（后端无法访问/调用失败，以及 `status` 当服务器报告无版本时），`2` 用法错误（未知命令/标志或错误值）。
### 启动 MCP 适配器
`jellyctrl mcp` 启动_stdio MCP 适配器。兼容的 `jellyfin-mcp` 二进制文件执行相同的操作，并保持支持。新启动器可以直接指向 `dist/mcp-bin.js` （或 `dist/cli.js mcp`）；引用文件路径 `dist/index.js` 的启动器继续工作；使用 `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
如果您从源代码检出运行而不是全局 npm 安装，请将 `command`/`args` 指向构建的 `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 代理
[Hermes 代理](https://github.com/NousResearch/hermes-agent) 从 `~/.hermes/config.yaml` 下的 `mcp_servers` 键读取 MCP 配置。添加一个条目：
```yaml
mcp_servers:
jellyfin:
command: "jellyfin-mcp"
env:
JELLYFIN_URL: "http://localhost:8096"
JELLYFIN_API_KEY: "your-api-key-here"
```
或在从源代码检出运行而不是全局 npm 安装时：
```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 通信。
## 示例提示
> 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`。
## 为什么不选择其他替代方案？
- **为什么不直接调用 Jellyfin REST API 而使用通用 HTTP 工具？** 你可以这样做，但调用者需要知道端点结构、构建查询字符串，并手动处理分页和 ID。jellyctrl 将有用的读取和报告操作封装为稳定的 CLI 命令，其 MCP 适配器公开了 56 个命名、模式验证的工具，并带有描述，因此模型可以选择 `jellyfin_pause_session` 而不是猜测 `POST /Sessions/{id}/Playing/Pause`。它还会遮蔽上游错误体和快速连接代码，在它们到达模型之前。
- **为什么不用 shell 脚本或几个 curl 别名？** 脚本适用于一项固定的任务。jellyctrl 为操作员提供了一个可重用的命令界面，而 MCP 适配器允许代理组成它事先未编程的步骤（“查找客厅会话，查看正在播放的内容，暂停它，然后向我的伴侣发送消息”），并在 Claude Desktop、Claude Code、Codex CLI、OpenClaw 和其他 MCP 客户端中重用相同的工具。
- **为什么不用 Jellyfin 网页仪表盘？** 仪表盘是供人类点击使用的。jellyctrl 适用于操作员和代理，通过命令、自然语言和较大工作流与其他工具一起操作。
## jellyctrl 不是什么
- **不是 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 捆绑
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
连接信息
猜你喜欢
暂无推荐服务器