内容
# 媒体栈 MCP
统一的[模型上下文协议](https://modelcontextprotocol.io/)服务器,用于家庭媒体栈。轮询 13 个服务,将事件/存储/健康记录到 PostgreSQL,并为 AI 代理提供工具来观察和操作您的媒体库。
## 功能
**观察者** — 持续轮询您的媒体服务并建立机构记忆:
- 记录抓取、导入、失败、升级、下载
- 存储使用情况及增长预测
- 跨所有服务的库大小
- 服务健康状况,检测降级
**执行者** — 受控的内容管理,带有两步确认协议:
- 搜索和添加内容到 Sonarr/Radarr/Lidarr
- 从 Sonarr/Radarr/Lidarr 中删除内容(可选文件删除)
- 通过 Seerr 请求或取消内容
- 触发缺失剧集/电影搜索
- 通过 Bazarr 触发字幕搜索
每次写入操作都需要显式确认后才能执行。破坏性操作(文件删除)使用缩短的 2 分钟确认过期时间,并附有醒目的警告。
## 支持的服务
| 服务 | 事件 | 库 | 健康 | 写入 |
|---|---|---|---|---|
| Sonarr | 历史记录 | 系列 + 大小 | 警告 | 添加、删除、搜索 |
| Radarr | 历史记录 | 电影 + 大小 | 警告 | 添加、删除、搜索 |
| Lidarr | 历史记录 | 艺术家 + 大小 | 警告 | 添加、删除、搜索 |
| Prowlarr | — | — | 警告 | — |
| Bazarr | 字幕历史记录 | — | 警告 | 字幕搜索 |
| Jellyfin | — | 按库计数 | ping | 收藏、已观看、收藏夹、播放列表 |
| Seerr | 请求管道 | — | ping | 请求、取消 |
| Audiobookshelf | — | 书籍 + 播客 | ping | — |
| Boxarr | 调度器运行 | — | ping | — |
| Suggestarr | 推荐统计 | — | ping | — |
| Dispatcharr | — | IPTV 通道 | ping | — |
| SABnzbd | 下载历史记录 | — | ping | — |
| qBittorrent | 状态差异 | — | ping | — |
服务通过环境变量自动发现。缺少的服务将被静默跳过。
## MCP 工具(27)
### 读取
- `mediastack_timeline` — 来自所有源的近期事件
- `mediastack_storage` — 磁盘使用情况及增长预测
- `mediastack_health` — 服务健康状态
- `mediastack_search` — 按标题搜索事件
- `mediastack_stats` — 数据库统计信息
- `mediastack_libraries` — 库大小和差异
- `mediastack_summary` — 精简摘要(每日/每周/每月)
### 写入(需要确认)
- `mediastack_search_content` — 搜索 *arr 查找 API
- `mediastack_add_content` — 添加到 Sonarr/Radarr/Lidarr
- `mediastack_list_profiles` — 显示质量配置文件和根文件夹
- `mediastack_request_content` — 通过 Seerr 请求
- `mediastack_search_missing` — 触发缺失内容搜索
- `mediastack_search_subtitles` — 触发 Bazarr 字幕搜索
- `mediastack_delete_content` — 从 Sonarr/Radarr/Lidarr 中删除(可选文件删除)
- `mediastack_cancel_request` — 取消 Seerr 请求
- `mediastack_confirm` — 执行预览的写入操作
### Jellyfin
- `mediastack_jellyfin_search` — 按名称搜索 Jellyfin 库
- `mediastack_jellyfin_genres` — 列出流派或按流派浏览项目
- `mediastack_jellyfin_favorites` — 列出用户的收藏(可选 `user_name`)
- `mediastack_jellyfin_collections` — 列出收藏或收藏中的项目
- `mediastack_jellyfin_playlists` — 列出播放列表或播放列表中的项目
- `mediastack_jellyfin_favorite` — 添加/删除项目到收藏
- `mediastack_jellyfin_watched` — 将项目标记为已播放/未播放
- `mediastack_jellyfin_collection_create` — 创建新收藏
- `mediastack_jellyfin_collection_modify` — 添加/删除收藏中的项目
- `mediastack_jellyfin_playlist_create` — 创建新播放列表
- `mediastack_jellyfin_playlist_modify` — 添加/删除/重新排序播放列表项目
## 快速入门
### 先决条件
- Docker 和 Docker Compose
- PostgreSQL(用于事件/存储/健康数据)
- 至少一个 *arr 服务正在运行
### 1. 创建数据库
```bash
docker exec postgres psql -U postgres \
-c "CREATE USER mediastack WITH PASSWORD 'your_password';" \
-c "CREATE DATABASE mediastack OWNER mediastack;"
```
### 2. 配置环境
```bash
cd mediastack-mcp
cp .env.example .env # 或链接到您的共享 env 文件
```
所需变量:
```env
# 数据库
DB_MEDIASTACK_NAME=mediastack
DB_MEDIASTACK_USER=mediastack
DB_MEDIASTACK_PASS=your_password
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
# 添加服务(仅配置的服务被轮询)
SONARR_URL=http://sonarr:8989
SONARR_API_KEY=your_key
RADARR_URL=http://radarr:7878
RADARR_API_KEY=your_key
# ... 等
```
### 3. 构建和运行
```bash
docker compose build
docker compose up -d
```
### 4. 验证
```bash
curl http://127.0.0.1:9202/health
```
```json
{
"status": "ok",
"events": 202,
"sources": 5,
"services": "Active services: radarr, sabnzbd, sonarr, ..."
}
```
## 身份验证(可选)
设置 `MEDIASTACK_AUTH_TOKEN` 以在 `/mcp` 和 `/ingest` 上需要 bearer token(401 没有它)。`/health` 保持开放用于 Docker 健康检查。当变量未设置时,所有内容的行为保持不变 — 现有部署在选择加入之前不受影响。
```bash
# 生成令牌
openssl rand -hex 32
```
主机端口绑定到 127.0.0.1 可以保护 LAN,但不能保护共享 Docker 网络的其他容器。该令牌关闭了该漏洞。
## 连接到 MCP 客户端
### Claude Code
添加到 `.mcp.json`:
```json
{
"mcpServers": {
"mediastack": {
"type": "stdio",
"command": "npx",
"args": ["mcp-remote", "http://127.0.0.1:9202/mcp"]
}
}
}
```
### Claude Desktop
添加到 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"mediastack": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://your-host:9202/mcp"]
}
}
}
```
对于非 HTTPS 连接,在参数中添加 `"--allow-http"`。
设置 `MEDIASTACK_AUTH_TOKEN` 时,通过 `mcp-remote` 的 `--header` 标志传递令牌(标志的一个数组元素,值的一个数组元素):
```json
"args": [
"mcp-remote", "http://127.0.0.1:9202/mcp",
"--header", "Authorization: Bearer your_token_here"
]
```
## 架构
```
app/
├── server.py # FastMCP 服务器,27 个工具,/health 端点
├── config.py # 服务从 env 变量自动发现
├── db.py # PostgreSQL 架构 + 查询
├── poller.py # 后台轮询引擎
├── confirmations.py # 写入确认协议(标准 5 分钟,文件删除 2 分钟)
├── retention.py # 数据汇总(90 天事件,14 天存储)
└── clients/ # 按服务 API 客户端(13 个服务)
```
- **传输:** 可流式 HTTP(FastMCP)
- **数据库:** PostgreSQL,具有 JSONB 元数据
- **轮询:** 在专用守护线程(自己的事件循环)中运行的异步轮询循环,具有可配置的间隔
- **去重:** 按 `source_event_id` 键控事件(唯一约束)
- **健康:** 稀疏表 — 仅记录状态更改
- **保留:** 事件汇总为每日摘要,90 天后;存储快照汇总为每日平均值,14 天后
## 配置参考
### 轮询间隔
| 变量 | 默认值 | 描述 |
|---|---|---|
| `MEDIASTACK_POLL_INTERVAL` | 300 | 事件轮询间隔(秒) |
| `MEDIASTACK_STORAGE_INTERVAL` | 3600 | 存储快照间隔(秒) |
| `MEDIASTACK_LIBRARY_INTERVAL` | 21600 | 库快照间隔(秒) |
| `MEDIASTACK_AUTH_TOKEN` | 未设置 | 在 `/mcp` 和 `/ingest` 上设置 bearer token 时 |
### 服务环境变量
<details>
<summary>API 密钥服务(URL + 密钥)</summary>
| 服务 | URL | 密钥 |
|---|---|---|
| Sonarr | `SONARR_URL` | `SONARR_API_KEY` |
| Radarr | `RADARR_URL` | `RADARR_API_KEY` |
| Lidarr | `LIDARR_URL` | `LIDARR_API_KEY` |
| Prowlarr | `PROWLARR_URL` | `PROWLARR_API_KEY` |
| Bazarr | `BAZARR_URL` | `BAZARR_API_KEY` |
| Jellyfin | `JELLYFIN_URL` | `JELLYFIN_API_KEY` |
| Seerr | `SEERR_URL` | `SEERR_API_KEY` |
| Audiobookshelf | `AUDIOBOOKSHELF_URL` | `AUDIOBOOKSHELF_API_KEY` |
</details>
<details>
<summary>凭证服务(URL + 用户名 + 密码)</summary>
| 服务 | URL | 用户名 | 密码 |
|---|---|---|---|
| qBittorrent | `QBITTORRENT_URL` | `QBITTORRENT_USERNAME` | `QBITTORRENT_PASSWORD` |
| Dispatcharr | `DISPATCHARR_URL` | `DISPATCHARR_USERNAME` | `DISPATCHARR_PASSWORD` |
| Suggestarr | `SUGGESTARR_URL` | `SUGGESTARR_USERNAME` | `SUGGESTARR_PASSWORD` |
</details>
<details>
<summary>其他</summary>
| 服务 | URL | 认证 |
|---|---|---|
| SABnzbd | `SABNZBD_URL` | `SABNZBD_API_KEY` |
| Boxarr | `BOXARR_URL` | 无 |
</details>
## 技术栈
- Python 3.14
- [FastMCP](https://github.com/jlowin/fastmcp)(MCP SDK)
- PostgreSQL(psycopg2)
- httpx(异步 HTTP 客户端)
- Uvicorn + Starlette
## 测试
四个层级 — 层级 1-3 在任何地方(笔记本电脑、CI)运行,无需媒体服务和凭证:
```bash
pip install -r requirements.txt -r requirements-dev.txt
pytest # 层级 1-3
pytest -m live # 层级 4(手动,选入)
```
1. **纯逻辑** — 确认协议(过期,续期,执行一次),扫描路径验证,环境自动发现,身份验证中间件
2. **模拟 HTTP** (respx,录制夹具) — 删除预览,客户端身份验证标头,*arr 历史记录解析和去重 ID
3. **真实 PostgreSQL** — 架构幂等性,事件去重,保留汇总,存储增长。使用 `TEST_DATABASE_URL`(如果设置,CI),否则使用一次性 [testcontainers](https://testcontainers-python.readthedocs.io/) 实例
4. **实时烟雾测试** (`pytest -m live`) — 对正在运行的部署进行只读检查;绝不执行写入或确认工具
## 如何构建
该项目完全使用 [Claude](https://claude.ai)(Anthropic 的 AI 助手)设计和实现,从详细的规格说明书开始。规格说明书涵盖了架构、服务集成、数据库架构、轮询策略、MCP 工具设计和分阶段交付计划。Claude 编写了所有代码、文档和 Docker 配置,跨越五个实现阶段。
人类贡献是产品愿景、需求和迭代反馈 — Claude 处理了工程。
## 许可证
[MIT](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息,可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
worldmonitor
实时全球情报仪表盘。基于人工智能的新闻聚合、地缘政治监测和基础设施跟踪,提供统一的态势感知界面。
hyperframes
编写HTML。渲染视频。为代理而建。
palmier-pro
带有AI生成的macOS视频编辑器
FireRed-OpenStoryline
FireRed-OpenStoryline 是一个 AI 视频编辑代理,它通过自然语言交互、LLM...
vexa
用于 Google Meet、Microsoft Teams 和 Zoom 的开源会议转录 API。自动加入机器人、实时 WebSocket...
MAI-UI
MAI-UI 提供专注于现实应用的 GUI 代理。