内容
# Tvheadend DVR MCP 服务器（仅限读取和创建）
一个最小化的模型上下文协议服务器，用于纯粹作为 DVR 使用 Tvheadend，从语音/语音助手。 它公开了 **四个** 工具，并且仅此而已：
| 工具 | 功能 | Tvheadend 端点 |
|------|--------------|--------------------|
| `search_epg` | 查找即将到来的节目（例如：“F1 比赛什么时候开始？”） | `GET /api/epg/events/grid` |
| `schedule_recording` | 从 EPG 事件创建一个一次性定时器 | `POST /api/dvr/entry/create_by_event` |
| `list_upcoming_recordings` | 显示已计划/正在进行的定时器 | `GET /api/dvr/entry/grid_upcoming` |
| `list_finished_recordings` | 显示成功完成的录音 | `GET /api/dvr/entry/grid_finished` |
没有取消、删除、编辑或重新录制的工具。 这就是这个服务器的全部目的。
## 为什么访问设计很重要
Tvheadend 的权限模型不提供“创建但永远不删除自己的录音”的权限 - 可以安排录音的用户通常也可以通过原始 API 删除自己的条目。 因此，这里通过两种方式强制实施“不删除/更改”：
1. **此服务器从不发出删除或修改请求。** 代码路径根本不存在。
2. **您为它提供一个专用的、低权限的 Tvheadend 用户。**
## 步骤 1 - 创建一个锁定的 Tvheadend 用户
在 Tvheadend 网页界面中：**配置 → 用户 → 访问条目 → 添加**。
创建一个条目（例如用户名 `voice`），并仅启用：
- **网页界面** - 任何 `/api/...` 调用都需要此权限。
- **视频录制器** - 需要此权限来创建 DVR 定时器。
禁用：*管理员*、*所有 DVR*、*所有 DVR（读/写）*、*HTSP*、*流媒体*、*更改设置*等。设置一个强密码。
可选的额外强化：
- 通过源 **IP/前缀** 限制条目到运行此服务器的机器。
- 如果您只想让某些频道可见，请设置 **最小/最大频道号**。
- 分配一个特定的 **DVR 配置文件**，并使用 `TVH_DVR_CONFIG` 指向它。
> 注意：此用户仍然可以通过原始 API 从技术上删除*其自己的*定时器。 保证它永远不会发生的原因是此服务器没有公开这些操作 - 请将凭证保密给服务器。
## 步骤 2 - 安装
需要 Python 3.9+。
```bash
pip install -r requirements.txt
```
## 步骤 3 - 配置（环境变量）
| 变量 | 是否必需 | 默认值 | 说明 |
|----------|----------|---------|-------|
| `TVH_URL` | 是 | - | 例如 `http://tvheadend.lan:9981`（不带尾部 `/`） |
| `TVH_USER` | 是 | - | 上面的 `voice` 用户 |
| `TVH_PASS` | 是 | - | 其密码 |
| `TVH_AUTH` | 否 | `digest` | `digest` 或 `basic`（服务器自动回退一次） |
| `TVH_TZ` | 否 | 系统本地 | 例如 `Europe/Helsinki` |
| `TVH_DVR_CONFIG` | 否 | 启用的第一个配置文件 | DVR 配置文件名称或 uuid |
| `TVH_VERIFY_SSL` | 否 | `true` | 设置 `false` 以适用于自签名 HTTPS |
| `TVH_EPG_LIMIT` | 否 | `8` | 默认最大 EPG 结果 |
## 步骤 4 - 使用 MCP 客户端注册（例如 Claude Desktop）
在 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"tvheadend-dvr": {
"command": "python3",
"args": ["/absolute/path/to/tvheadend_dvr_mcp.py"],
"env": {
"TVH_URL": "http://tvheadend.lan:9981",
"TVH_USER": "voice",
"TVH_PASS": "your-strong-password",
"TVH_TZ": "Europe/Helsinki"
}
}
}
}
```
## 典型的口语流程
1. *"下一场 Formula 1 比赛什么时候开始？"* → `search_epg("Formula 1")` 返回节目和 `event_id`。
2. *"录制它。"* → `schedule_recording(event_id=...)`。
3. *"我有什么计划？"* → `list_upcoming_recordings()`。
4. *"我这周录制了什么？"* → `list_finished_recordings()`。
## 快速手动检查（不需要 MCP 客户端）
您可以通过设置环境变量并运行它来验证服务器启动并连接；它通过 stdio 发送 MCP，因此它将等待客户端。 要独立检查 Tvheadend 的连接性：
```bash
curl --digest -u voice:PASS \
'http://tvheadend.lan:9981/api/dvr/entry/grid_upcoming?limit=5'
```
