内容
<p align="center">
<img src="docs/assets/jellyfin-mcp-banner.jpg" alt="jellyfin-mcp banner" width="900">
</p>
<h1 align="center">jellyfin-mcp</h1>
<p align="center"><strong>通过工具调用与 Jellyfin 服务器对话。</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="#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 version">
<img src="https://img.shields.io/github/actions/workflow/status/lidless-labs/jellyfin-mcp/ci.yml?branch=main&style=for-the-badge&label=ci" alt="CI status">
<img src="https://img.shields.io/badge/MCP-server-8A2BE2?style=for-the-badge" alt="MCP server">
<img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License">
</p>
jellyfin-mcp 是为 [Jellyfin](https://jellyfin.org)（一个免费的自托管媒体服务器）设计的模型上下文协议（MCP）服务器。这样，AI 客户端可以读取和控制您的媒体库、会话和用户，通过键入的工具调用。您需要它，因为询问“客厅里正在播放什么，暂停它”或“扫描电影库”比在 Jellyfin 仪表板上点击更快，并且代理可以链接这些步骤。它与通用 HTTP 工具或手写的脚本不同，它提供了 56 个模式验证的工具，每个破坏性操作都有 `confirm: true` 门控和 MCP 注释，允许客户端将这些调用路由到人工审批。
> **状态：WIP。** 每天都在使用真实的 Jellyfin 服务器，但工具表面仍在稳定和破坏性更改之间切换。如果您需要稳定性，请固定已发布的版本。
与 [arr-cli](https://github.com/lidless-labs/arr-cli)（*arr stack CLI*）配套。arr-cli 处理获取内容；jellyfin-mcp 处理提供、监控和控制播放。
## 功能
- **56 个 MCP 工具**，涵盖系统信息、库、用户、会话、项目、计划任务、用户数据写入、播放列表、收藏、发现和快速连接
- 播放控制：暂停/恢复/停止/跳转/下一曲/上一曲/音量/静音/音频流/字幕流/投射（远程播放）/发送消息/批量会话控制
- 用户数据写入：标记已观看/未观看、添加/删除收藏、预览或清除继续观看的恢复位置、设置恢复位置
- 播放列表：创建、列出、追加、删除条目
- 收藏：创建、添加、删除
- 发现：恢复队列、下一集、类似项目
- 快速连接：检查状态、授权用户的待定代码
- 库扫描触发（每个库或全部）
- 用户管理：列出、创建、删除、启用/禁用、重置密码
- 最近事件的活动日志查询
- 破坏性/特权操作（`restart`、`shutdown`、`delete_user`、`set_user_password`、`quick_connect_authorize`、`jellyfin_clear_continue_watching`、批量会话控制、恢复位置写入）需要明确的 `confirm: true`
- 上游 Jellyfin 错误响应在返回给客户端之前会进行总结（仅状态）；完整响应正文会记录到操作员的 stderr 中，因此不会将内部服务器详细信息暴露给模型
- 与 Claude Desktop、Claude Code、OpenClaw、Hermes Agent、Codex CLI 和任何 MCP 兼容的客户端配合使用
## 安装
```bash
npm install -g jellyfin-mcp
```
或从源代码：
```bash
git clone https://github.com/lidless-labs/jellyfin-mcp.git
cd jellyfin-mcp
npm install
npm run build
```
## 快速入门
将以下内容添加到您的 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/对话框
- `jellyfin_seek_session` - 跳转到秒数位置
- `jellyfin_next_track` / `jellyfin_previous_track`
- `jellyfin_set_volume` (0-100) / `jellyfin_set_mute` (静音/取消静音/切换)
- `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）
- `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`
## 配置
在 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 配置，位于 `mcp_servers` 键下。添加一个条目：
```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 现在正在积极播放什么？
调用带有 `activeOnly=true` 的 `jellyfin_list_sessions`。
> 暂停客厅里正在播放的内容
调用 `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` 以解析目标用户，然后带有 `userId` 和 `confirm: true` 的 `jellyfin_clear_continue_watching`。
> 显示该节目的继续观看内容将被清除。
调用带有系列 ID 的 `jellyfin_preview_continue_watching_clear`，然后再进行更改。
> 我打开了一个节目中的多个集。保留最新集并清除其余集。
调用带有系列 ID、用户 ID 和 `confirm: true` 的 `jellyfin_clear_episode_continue_watching_except_latest`。
> 将此电影设置为 42 分钟恢复。
调用带有 `positionSec=2520` 和 `confirm: true` 的 `jellyfin_set_resume_position`。
> 我的下一个节目是什么？
调用带有用户 ID 的 `jellyfin_get_next_up`，可选地使用 `seriesId` 进行缩小。
> 批准我的手机 Jellyfin 登录。代码是 `ABCDEF`。
调用 `jellyfin_list_users` 以解析目标用户，然后带有 `code`、`userId` 和 `confirm: true` 的 `jellyfin_quick_connect_authorize`。
## 为什么不选择替代方案？
- **为什么不用通用 HTTP 工具从 Jellyfin REST API 调用？** 你可以，但模型必须知道端点形状、构建查询字符串，并在每次调用时手动处理分页和 ID。jellyfin-mcp 将有用的操作包装为 56 个命名、模式验证的工具和描述，因此模型选择 `jellyfin_pause_session` 而不是猜测 `POST /Sessions/{id}/Playing/Pause`。它还会遮蔽上游错误正文和快速连接代码，然后再到达模型。
- **为什么不用 shell 脚本或几个 curl 别名？** 脚本适用于一个固定的任务。MCP 服务器允许代理组成它没有预先编程的步骤，并在 Claude Desktop、Claude Code、Codex CLI、OpenClaw 和任何其他 MCP 客户端中重用相同的工具。
- **为什么不用 Jellyfin 网页仪表板？** 仪表板适用于人类点击。jellyfin-mcp 适用于自然语言中的代理代表您采取行动，并将媒体服务器操作与其他 MCP 服务器一起链接到更大的工作流中。
## jellyfin-mcp 不是什么
- **不是 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 服务器的网络出口。它作为标准输入/输出 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
连接信息
猜你喜欢
暂无推荐服务器