mcp-kodi

mcp-kodi 是一个 MCP（Model Context Protocol）服务器，用于通过 Kodi 的 JSON-RPC API 控制 Kodi 媒体播放器。项目使用 C 语言在 GLib 栈上编写，是一个独立、净室实现的自由软件，以 GNU GPL v3.0 许可发布。

用途 mcp-kodi 的目标是让任何兼容 MCP 的 AI 助手来操控 Kodi 媒体播放器。它不是一个面向用户的 CLI 工具：用户与 AI 对话，AI 调用本服务器提供的工具，服务器再向 Kodi 发送 JSON-RPC 请求。唯一的接口是 stdio 上的 MCP。项目愿景不仅是“按按钮”，而是让 AI 重新塑造媒体播放体验——根据用户的情绪和偏好编排播放列表、从上次中断处继续、实时调整内容，并推荐用户自己难以发现的内容。

主要能力 当前版本（v0.2.0dev）已提供一组用途明确的工具，覆盖以下方面：

• 播放控制与音频：play / pause / stop、playfile、volume、mute / unmute 等。
• 搜索与发现：searchmedia、contributors。
• 播放与队列：queue、getplaylist、dropplaylists 等。
• 记录与逃生舱：history、nowplaying、rpc。

大多数动作类工具会返回一个小的播放器状态快照，形如 { "state": "playing"|"paused"|"stopped", "type", "time", "totaltime", "progress", "nowplaying": { "media", "id", "file", "label", "title", … } }，并将已加载媒体信息嵌套在 nowplaying 下，附带 artist、album、track、showtitle、season、episode 等按媒体类型适用的字段；progress 会给出类似 "15:38 / 46:40 (33%)" 的可读形式。音量类工具返回 { "muted", "volume" }（volume 还会附带 min / max 边界）。读取类工具（searchmedia、contributors、getplaylist、history）返回各自的分页结果封装。

除 rpc 外，每个工具都以 MCP outputSchema（规范修订版 2025-06-18）声明这些结果形状，并将每次成功结果同时以 structuredContent 和 JSON 文本块返回，使支持 schema 的客户端无需解析即可校验和使用结果。rpc 不声明任何形状：它原样返回 Kodi 的原始回复。

每个工具通过键（instance）指定一个已配置的 Kodi 设备；省略则使用配置的默认设备（有一个例外：省略 instance 时 history 跨越所有设备）。

rpc 逃生舱 rpc 会将你指定的任意 JSON-RPC 方法 POST 到目标设备，并原样返回 Kodi 的未塑形结果。该功能强大且不受约束，因此默认禁用，并按设备单独开启：只有当某设备的配置对象带有 "allow_rpc": true 时，该设备才允许 rpc。此标志只能通过手动编辑 config.json 授予——它被有意设计为 instances 工具无法写入的字段，因此 AI 永远无法自行启用逃生舱。对未开启的设备调用 rpc 会返回清晰的错误，且不会向 Kodi 发出请求。完整的 Kodi 方法面见 docs/kodi-jsonrpc-catalog.md。

使用方式 准备 Kodi 以支持远程控制：在 Kodi 中打开“设置 → 服务 → 控制”，开启“允许通过 HTTP 进行远程控制”，并在此处设置用户名和密码。这些凭据将以 user:pass 形式写入本服务器的配置，作为 auth。

由于 mcp-kodi 使用 HTTPS，常规使用中需在 Kodi 的纯 HTTP 控制端口前放置一个小型反向代理。使用 Caddy 配合 tls internal 是简便之选：它终止 HTTPS 并转发到本机上的 Kodi。将设备的 host 指向该代理，并设置 insecure: true 以接受其自签名证书。完整的分步指南（Kodi 菜单、安装 Caddy、Caddyfile）见 docs/kodi-server-setup.md。

注册 Kodi 设备有两种方式：

1. 让 AI 完成：MCP 服务器加载后，告诉助手你的 Kodi 地址和登录信息，它就会通过 instances 工具（set）注册设备，将条目写入配置文件。
2. 手动编辑 config.json。有两项被有意设为 AI 不可操作，只能手动编辑：密码（auth 是只写的，instances 工具从不返回已存储的密码，因此助手可以注册设备但永远无法读回凭据）；逃生舱（allow_rpc 不是 instances 工具可写入的字段，因此助手永远无法自行授予不受限的 rpc 直通）。

配置文件位于 ${XDG_CONFIG_HOME:-~/.config}/mcp-kodi/config.json，保存命名 Kodi 设备映射并指定一个 default。该文件以 0600 创建于 0700 目录中（因含密码），当 instances 工具修改它时会原子化写回。若没有配置文件，可以完全通过环境变量定义一个设备，应用于隐式默认设备：KODI_HOST、KODI_AUTH、KODI_SCHEME，以及在 KODI_CURL_OPTS 中的 -k（→ insecure）。若既无文件也无环境变量，服务器会以明确错误退出，提示你进行配置。旧版 version: 1 的扁平文件（单个顶层 host / auth /…）会被读取为名为 default 的一个设备，并在下次保存时重写为 version: 2 结构。注意：配置仅在启动时读取一次；手动编辑 config.json（例如设置 allow_rpc）后需重启服务器以重新读取。

注册到 MCP 客户端：在 Claude Desktop 或其他 MCP 客户端中，添加一个指向该二进制文件的 stdio 服务器条目。注册后即可向助手发出诸如“客厅的播放器在放什么？”（nowplaying）、“找到 Pink Floyd 的 Animals 并播放”（searchmedia → playfile）或“把卧室静音”（mute）等指令。

适用场景 适用于家庭局域网中的 Kodi 媒体播放器控制：设备通常位于路由器/防火墙后的家庭局域网，不暴露于互联网，因此在其中开启 HTTP 控制接口通常安全。登录名/密码和 HTTPS 代理提供纵深防御。适合希望用自然语言让 AI 管理媒体播放、搜索、队列和播放历史的用户。

限制与注意事项

• config.json 以明文存储 Kodi 密码（权限 0600），应像保护其他凭据文件一样保护它。
• insecure: true 会为该设备禁用 TLS 证书验证。在 Caddy 的 tls internal 自签名证书后是正确的选择，但意味着连接是加密的、而非针对 CA 认证的——请将代理保持在受信任网络中。
• rpc 逃生舱可调用任意 JSON-RPC 方法（包括 System.Shutdown 等破坏性方法）。它默认关闭，只有为特定设备手动设置 allow_rpc: true 后才启用。仅在信任助手不受约束地操作时才启用。
• 当前为 v0.2.0dev 早期版本，功能仍在快速迭代。

项目由 Laszlo Pere 开发，以 GNU GPL v3.0 许可发布，不提供任何担保。可通过 GitHub Sponsors 支持项目。

（注：资料中未提供具体的安装命令、依赖项列表或更多工具参数细节，此处未作补充。）