内容
# mcp-kodi
[](LICENSE)
[](https://github.com/sponsors/laszlopere)
[](https://github.com/laszlopere/mcp-kodi/commits)
MCP 服务器，允许 AI 助手通过 Kodi 的 JSON-RPC API 控制 Kodi 媒体播放器。使用 C 语言在 GLib 栈上编写。
没有面向用户的命令行界面：您与 AI 对话，AI 调用此服务器的工具，服务器与 Kodi 进行 JSON-RPC 通信。唯一的接口是通过标准输入输出的 MCP。
**目标**。计划是一个完整、功能齐全的软件包，让任何兼容 MCP 的 AI 转换整个媒体播放器的体验 — 不仅仅是按键操作，而是重新定义您如何发现、排队和享受媒体。告诉助手您想听什么，让它控制整个房间：建立晚上的播放列表，从昨晚停止的地方继续播放，根据需要进行调整，并显示您可能永远不会自己找到的内容。我们旨在创造一些真正的新事物 — 一种令人惊叹的、全新的媒体播放器使用方式。
> **状态 — 早期，但已经非常出色（v0.2.0dev）**。一组不断增长的专用工具涵盖了传输、音量、搜索、队列管理和播放历史。除了这个列表之外，构建还具备了 **`rpc` 出口** （见下文）：一个可选择的通往任意 Kodi JSON-RPC 方法的通道。在一流工具和出口通道之间，助手已经可以驱动 Kodi 公开的几乎所有功能 — 已经足够出色，我们决定在功能完善之前就发布。预计会有频繁的更新。
---
## 功能
每个工具都针对配置的 Kodi 设备（通过 `instance` 键）；省略它时，使用配置的 `default` 设备（有一个例外：`history` 跨所有设备，当省略 `instance` 时）。
**传输和音频**
| 工具 | 功能 |
| --- | --- |
| `play` | 按下遥控器的 **播放** 键 — 在目标设备上恢复或开始播放。 |
| `pause` | 按下 **暂停** 键 — 暂停当前播放器。 |
| `stop` | 按下 **停止** 键 — 停止当前播放器 **并清除播放列表** ，以便不会留下任何排队项目。 |
| `skipnext` | 按下 **跳过下一曲** 键 — 跳到当前播放列表中的下一曲/章节。 |
| `skipprevious` | 按下 **跳过上一曲** 键 — 跳到上一曲/章节（或重新开始当前项目）。 |
| `volume` | 通过相对有符号步长（百分比）调整音量；步长 `0`/省略时直接读取。永不为绝对级别，因此助手无法通过猜测使设备最大音量或静音。返回音量、静音状态和 `0`-`100` 界限。 |
| `mute` | 静音设备的音频输出。 |
| `unmute` | 取消静音设备的音频输出。 |
| `nowplaying` | 报告当前正在播放的内容而不改变任何内容 — 同时也是一个可用性和状态探测器。 |
| `notify` | 在设备的屏幕上显示通知 — 标题 + 消息，可选图标（`info`/`warning`/`error` 或任何图像路径/URL）和显示时间。不影响播放。 |
**搜索和发现**
| 工具 | 功能 |
| --- | --- |
| `searchmedia` | 按名称查找可播放的 **叶子文件** ，跨越 `music` / `tv-show` / `movie` ，带有分页（`limit`/`offset`）和总计数。音乐 `title` 匹配 **专辑** ；`song` 参数匹配特定曲目标题（不限于特定艺术家），可按 `artist`/`title`/`number` 缩小范围。对于电视，`title` 匹配 **剧集** ；`episodetitle` 参数查找特定剧集标题（可按剧集 `title` 缩小范围）。电影/电视剧查询还可按 `actor`/`director` 筛选。通过名称解析库，因此助手按标题操作，而不是数字 ID。仅媒体项目 — 人员查找位于 `contributors` 中。 |
| `contributors` | 查找或列出 **人员** — 乐队、独唱歌手、作曲家、演员、导演 — 通过可选名称子字符串和/或 `type`。每行显示名称的匹配位置（`albums`/`songs`/`movies`/`tvshows`）；将确切名称反馈到 `searchmedia` 以进行深入查找。 |
| `audio_and_subtitle_info` | 检查电影或剧集的 **音频轨道和字幕** ，在播放前，从 Kodi 的缓存 `streamdetails` 中获取 — 无需播放。通过 `type`+`id` （`searchmedia` 行）或 `file` 命名项目。返回 `{ file, audio:[{ index, codec, channels, language }], subtitle:[{ index, language }], video:[…] }`。**仅嵌入流** — 外部 `.srt` 副文件和 Kodi 未扫描的文件返回为空数组。 |
| `set_audio_and_subtitle` | 切换当前正在播放的视频的 **音频轨道和/或字幕** ，通过 `audio_and_subtitle_info` 中的 `index`。`audio` 是流索引；`subtitle` 是流索引或 `"off"` 以隐藏字幕。省略参数以保持该流不变；提供至少一个。仅限视频。返回播放器状态快照。 |
**播放和队列**
| 工具 | 功能 |
| --- | --- |
| `playfile` | 通过路径播放文件（通常是 `searchmedia` 结果的 `file`）。Kodi 自动选择音频/视频播放器。适用于任何可达路径，无论是否在库中。磁盘上不存在的文件（过时的库条目）被报告为错误。 |
| `queue` | 在当前正在播放的项目后面追加一个项目（`searchmedia` 库 ID `type`+`id` 或 `file` 路径）；`next: true` 将其插入当前项目之后。必须已经有项目正在播放。磁盘上不存在的文件被拒绝。 |
| `getplaylist` | 读取队列而不改变它 — 活动播放器的播放列表，或命名播放列表（`audio`/`video`/`picture`），以及当前播放位置。只读；空队列为空列表。 |
| `dropplaylists` | 清空 **所有** 队列（音频、视频、图片），只需一次调用。当前项目继续播放 — 只有排队在后面的项目被删除。不可撤销；如果内容重要，请先使用 `getplaylist` 检查。 |
**记录和出口**
| 工具 | 功能 |
| --- | --- |
| `history` | 从 **本地** 播放日志中列出最近播放的项目，该日志作为每个影响播放的调用的副作用写入。可选的 ISO-8601 `since`/`until` 窗口加上应用侧过滤器 — `media`、`kind`、`artist`、自由文本 `match`、精确 `id` — 全部 AND 组合，带有 `limit`/`offset`/`order` 分页和仅计数模式。仅读取本地日志 — 无 Kodi 调用，因此即使无法访问任何设备也有效。省略 `instance` 返回 **所有** 设备。 |
| `instances` | 读取或修改服务器自己的实例配置（`get`/`set`/`remove`）。不进行 Kodi 调用；永不返回存储的密码。 |
| `rpc` | **出口** — 将原始 JSON-RPC 方法发送到 Kodi 并返回其回复不变。默认关闭；按实例选择（见下文）。 |
大多数操作工具返回一个小的播放器状态快照 — `{ "state": "playing"|"paused"|"stopped", "type", "time", "totaltime", "progress", "nowplaying": { "media", "id", "file", "label", "title", … } }` — 将播放器状态（`state`/`type`/`time`/`totaltime` 加上可读的 `progress` 子句，如 `"15:38 / 46:40 (33%)"`）放在顶部，并将加载的媒体嵌套在 `nowplaying` 下，并带有其特定媒体字段（适用时）（`artist`、`album`、`track`、`showtitle`、`season`、`episode`）— 因此助手始终看到其操作的效果：这涵盖了 `play`/`pause`/`stop`、`playfile`、`queue`、`dropplaylists` 和 `nowplaying`。音频工具 `volume`/`mute`/`unmute` 返回 `{ "muted", "volume" }`（`volume` 还添加了 `min`/`max` 界限）。读取工具（`searchmedia`、`contributors`、`getplaylist`、`history`）返回其自己的分页结果信封。
除了 `rpc` 之外的每个工具都声明这些形状为 MCP `outputSchema` （规范修订版 2025-06-18），并将其每个成功的返回结果镜像为 `structuredContent`，与 JSON 文本块一起，因此支持模式的客户端可以在不解析的情况下验证和消耗结果。每个描述还内联声明了结果形状 — 客户端显示的模型。`rpc` 声明为无；它原样返回 Kodi 的原始回复，没有固定的形状。
### `rpc` 出口
`rpc` 将您命名的任意 JSON-RPC 方法发送到目标设备，并返回 Kodi 的原始 `result`，无形状：
```jsonc
// 例如：提高 GUI 音量，激活窗口，发送输入操作…
rpc { "instance": "hall", "method": "GUI.ActivateWindow", "params": { "window": "home" } }
```
此功能强大且无约束，因此 **默认禁用** ，并 **按实例启用** （见下文）。设备仅在配置对象带有 `"allow_rpc": true` 时才允许 `rpc`。该标志 **仅通过手动编辑 `config.json` 授予** — 它故意 *不是* `instances` 工具可以写入的字段，因此助手永远无法启用其自己的出口。将设备选择为开启是一个明确的、独立于带的、人工决定；调用未开启的设备的 `rpc` 返回干净的错误并且不进行 Kodi 请求。
有关完整的 Kodi 方法界面，请参见 [docs/kodi-jsonrpc-catalog.md](docs/kodi-jsonrpc-catalog.md)。
---
## 配置
### 为远程控制设置 Kodi
在 mcp-kodi 可以访问设备之前，Kodi 必须允许远程控制。在 Kodi 中，打开 **设置 → 服务 → 控制** 并启用 **通过 HTTP 允许远程控制** ，然后设置 **用户名和密码** 。这些凭证与此服务器的配置中 `auth` 相同，格式为 `user:pass`。
mcp-kodi 使用 **HTTPS**，因此在正常使用中，您需要在 Kodi 的纯 HTTP 控制端口前放置一个小型反向代理。[Caddy](https://caddyserver.com) 搭配 `tls internal` 是简单的选择：它终止 HTTPS 并将请求转发到本地的 Kodi。 将实例的 `host` 指向代理，并设置 `insecure: true` 以接受其自签名证书。完整的逐步指南 — 确切的 Kodi 菜单、安装 Caddy 和 Caddyfile — 在 [docs/kodi-server-setup.md](docs/kodi-server-setup.md) 中。
大多数 Kodi 播放器已经位于路由器的家庭局域网（LAN）后面，并且不暴露在互联网上，因此启用 HTTP 控制接口通常是安全的。登录/密码和 HTTPS 代理增加了防御深度 — 只需将代理放在受信任的网络上，不要将端口转发到开放的互联网上。
### 注册 Kodi 实例
有两种方法可以添加设备。最简单的方法是 **让 AI 代为注册**：加载 MCP 服务器后，只需告诉助手关于您的 Kodi — 其地址和登录 — 然后它通过 `instances` 工具（`set`）为您注册实例，将条目写入配置文件中。
您也可以 **手动操作** ，通过直接编辑 `config.json`。有两个功能故意 **不允许 AI 操作** ，因此手动编辑是唯一的方法来设置它们：
- **密码**。`auth` 是只写的 — `instances` 工具永远不会返回存储的密码，因此助手可以注册一个设备，但永远无法读取回凭证。如果您不想让 AI 看到密码，可以自己将其输入到文件中。
- **出口**。`allow_rpc` **不是** `instances` 工具可以写入的字段，因此助手永远无法授予自己不受限制的 `rpc` 通道。启用它始终是一个明确的、独立于带的、人工编辑。
### 配置文件
服务器读取 `${XDG_CONFIG_HOME:-~/.config}/mcp-kodi/config.json`。它包含命名 Kodi 实例的映射，并命名一个 `default`：
```json
{
"version": 2,
"default": "hall",
"instances": {
"hall": { "name": "客厅电视", "host": "hall.example.local:8443", "auth": "kodi:<password>", "scheme": "https", "insecure": true, "allow_rpc": true },
"bedroom": { "name": "卧室", "host": "bedroom.example.local:8443", "auth": "kodi:<password>", "scheme": "https", "insecure": true }
}
}
```
| 字段 | 含义 |
| --- | --- |
| 实例 *键* | 每个工具引用的短 ID（`hall`、`bedroom` 等）。 |
| `default` | 工具省略 `instance` 时使用的键。 |
| `name` | 可选的人类可读标签，在工具模式中显示。 |
| `host` | 设备（或其前面的代理）的 `host[:port]`。 |
| `auth` | HTTP 基本身份验证凭证，格式为 `user:pass`。只写 — 永远不会被 `instances get` 返回。 |
| `scheme` | `http` 或 `https`（默认为 `https`）。 |
| `insecure` | `true` 接受自签名证书 — 等同于 `curl -k` 的 JSON。 |
| `allow_rpc` | `true` 为此设备选择 `rpc` 出口。仅限手动编辑。 |
文件以 `0600` 模式创建在 `0700` 目录中（它包含密码），并在 `instances` 工具更改时以原子方式写回。
**没有配置文件？** 可以完全从环境中定义单个设备，应用于隐式 `default` 实例：`KODI_HOST`、`KODI_AUTH`、`KODI_SCHEME` 和 `-k` 在 `KODI_CURL_OPTS`（→ `insecure`）中。如果既没有文件也没有环境，服务器会退出，并显示明确的错误，告诉您配置。
旧版 `version: 1` 平面文件（单个顶级 `host`/`auth`/…）被读取为一个名为 `default` 的实例，并在下一次保存时重写为 `version: 2` 形状。
> **注意：** 配置在 **启动时读取一次** 。在手动编辑 `config.json` 后（例如，设置 `allow_rpc`），重启服务器以重新读取文件。
---
## 注册到 MCP 客户端
### Claude 代码
```sh
# 用户范围使工具在每个项目中都可用
claude mcp add --scope user kodi -- /path/to/mcp-kodi/src/mcp-kodi
```
### Claude 桌面版 / 其他 MCP 客户端
添加一个指向二进制文件的标准输入/输出服务器条目：
```json
{
"mcpServers": {
"kodi": {
"command": "/path/to/mcp-kodi/src/mcp-kodi"
}
}
}
```
注册后，询问您的助手类似的问题，例如 *"客厅的播放器正在做什么？"*（`nowplaying`）， *"查找平克·弗洛伊德的专辑《动物》并播放它"*（`searchmedia` → `playfile`），或 *"静音卧室的音量"*（`mute`）。
---
## 安全注意事项
- `config.json` 以纯文本存储 Kodi 密码，模式为 `0600`。像其他凭证文件一样保护它。
- `insecure: true` 禁用该设备的 TLS 证书验证。它是在 Caddy 的 `tls internal` 自签名证书后面正确选择，但在受信任的网络上保持代理。
---
## 支持这个项目
如果这个项目对您有帮助，请考虑通过 [GitHub 赞助](https://github.com/sponsors/laszlopere) 支持它。每一份支持都使其保持活跃 — 为频繁发布提供资金，并实现这一愿景。
如果您仍在犹豫：请您的 Claude 评估这个项目是否适合您 — 如果它推荐（像大多数 Claude 一样），请通过成为赞助者来支持它。
