seerr-mcp-server

---

概览

Jellyseerr 和 Overseerr 的媒体请求工作流：搜索由 TMDB 提供数据的影视作品，确认确切匹配项，检查可用性和请求状态，然后创建受保护的请求，由 Radarr/Sonarr 执行。权限、配额、路由和状态均由 Jellyseerr 管理；此服务绝不会直接调用 Radarr/Sonarr。可作为 stdio 进程或本地 Streamable HTTP 服务运行。

工具

工具	描述
seerr_search_media	按标题搜索电影和电视节目；返回按相关度排序的匹配项，包含 TMDB ID、年份、简介，以及 Jellyseerr 已跟踪该作品时解码后的可用性。这是提交请求前必需的第一步。
seerr_get_media	按 TMDB ID + 媒体类型获取准确的电影/节目详情，以便在写入前确认标题；对于电视节目，可获取按季摘要或某一季的剧集列表。
seerr_list_requests	按状态/类型/请求者筛选并列出近期请求；会回显已应用的筛选条件，并解码每个数字状态。标题需通过 includeTitles 显式启用。
seerr_request_media	受保护的写入操作。 默认预览请求负载（mode: preview）；只有在设置 mode: request 且确认已获接受后，才会创建请求。
seerr_request_status	按 ID 获取单个请求，包含标题、解码后的请求状态和媒体可用性（包括 4K）、请求者、路由摘要，以及根据当前状态调整的后续步骤提示。
seerr_service_options	汇总已配置的 Radarr/Sonarr 服务、默认质量配置文件和实例功能标志（4K、部分请求、特别篇、媒体服务器）。除非设置 includePaths，否则会隐藏文件系统路径。

资源

资源	说明
seerr://request/{requestId}	单个请求的一次性摘要 — 解码后的状态、媒体可用性、请求者和路由信息。与 seerr_request_status 一致。

所有请求数据也可通过工具访问 — 请求枚举由 seerr_list_requests 负责（仅通过工具访问的路径）。

功能参考

seerr_search_media _工具

• 使用 mediaType: movie | tv | all 搜索标题；不包含人物。page 范围为 1–1000；limit 范围为 1–20，默认值为 10。
• 返回 TMDB 匹配结果，以及已跟踪标题的解码后 status / status4k。无结果时返回 []，并附带指导提示。
• 可选的 ISO 639-1 language 用于选择本地化标题和简介。

---

seerr_get_media _工具

• 返回可用性，以及该标题的任何现有未完成请求（避免重复请求）
• 电视节目：省略 seasonNumber 可获取逐季摘要，传入该参数可获取指定季的剧集列表（第 0 季为特别篇）
• 无法解析的 TMDB ID 会返回类型化的 media_not_found，并附带搜索恢复提示（Jellyseerr 的原始 HTTP 500 会在服务层进行分类）

---

seerr_list_requests _工具

• 按生命周期 filter、mediaType 和 requestedById 筛选；按 added 或 modified 排序，可选择升序或降序。take 范围为 1–100，默认值为 20；skip 用于选择偏移量。
• 返回解码后的状态、请求者 { id, displayName }，以及包含已应用筛选条件的补充信息。
• includeTitles: true 会按不同标题各联查一次媒体标题（默认关闭）；无法解析的行会保留其数据，并在提示中说明。

---

seerr_request_media _工具

• 受保护的写入操作。 mode: preview（默认）会返回已解析的标题和确切的 POST /request 负载，但不会写入。mode: request 会请求确认，确认与同一调用方、标题和负载绑定；拒绝、取消或无效的回答会返回 request_cancelled。
• 电视节目请求必须指定 seasons: "all" 或类似 [1, 2] 的列表；第 0 季（特别篇）需要启用特别剧集。任何 POST 操作前都会先检查实例功能；输出中会显示现有请求，重复请求会被拒绝并返回 duplicate_request。
• 可选的路由覆盖项：serverId、profileId、rootFolder、languageProfileId。省略这些参数时将使用 Jellyseerr 默认值。

---

seerr_request_status _工具

• 接受来自 seerr_request_media 的 created.requestId 或 seerr_list_requests 的 requestId。请求不存在时返回 request_not_found。
• 返回解码后的 requestStatus、mediaStatus / mediaStatus4k、请求者 { id, displayName }、路由信息（serverId、profileName、is4k）以及 stateGuidance。
• 每次调用都会联查 title；不存在 tmdbId 或查找失败时不会返回该字段。

---

seerr_service_options _工具

• 返回实例版本、媒体服务器、功能标志（movie4kEnabled、series4kEnabled、partialRequestsEnabled、specialEpisodesEnabled）、服务 ID、默认值和质量配置文件。
• 服务请求失败时，会保留可用结果并附带提示。
• includePaths: true 会公开根文件夹路径和可用空间；默认情况下两者都会省略。

---

seerr://request/{requestId} _资源

• 接受来自 seerr_request_media 或 seerr_list_requests 的 requestId；请求不存在时返回 request_not_found。
• 与 seerr_request_status 一致，包括脱敏和标题联查。不存在 tmdbId 或查找失败时不会返回 title；资源不接受逐次读取选项。

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔的身份验证（none / jwt / oauth）、可切换的存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

HTTP 需要有状态会话，以支持 2025 年的确认流程；显式设置 MCP_SESSION_MODE=stateless 会导致启动失败。许可记录在十分钟后过期，记录发生变更或被重放时会再次请求许可。在单个进程内，兑换操作会排除并发重试；创建请求只会尝试一次 POST，不会自动重试。跨实例的读取和删除不是原子操作：对于路由重试，请使用共享且强一致的文件系统、Supabase 或 Cloudflare D1 存储，并留意重复提交竞争；Cloudflare KV 不适合存储许可记录。

Seerr 专属功能：

• 仅支持读取和受保护的请求操作——管理员级接口（批准/拒绝、重试、编辑/删除、媒体/文件删除、用户/设置/同步）是出于设计而非 API 限制，故意排除的
• 在单一规范化入口集中处理个人身份信息/基础设施信息脱敏——请求者仅投影为 { id, displayName }；操作员邮箱、Plex/Jellyfin 令牌和 serviceUrl 不会出现在输出中；文件系统路径需通过 includePaths 显式启用
• 在单一辅助函数中集中解码状态——请求和媒体状态（包括单独的 4K 可用性）在所有地方都解码为 { raw, label }，并可兼容未来新增的 Jellyseerr 状态码
• 根据缓存的实例设置验证功能支持情况，可在大多数错误请求到达 API 前将其拦截
• 短 TTL 设置缓存避免每次预览都产生往返请求

便于 Agent 使用的输出：

• 来源信息和披露——搜索结果会回显生效的查询；达到上限的列表会说明结果已截断；服务的某个部分出现故障时会显示提示，而不是悄悄丢弃数据
• 带类型且可采取行动的错误——media_not_found、request_not_found、seasons_required、four_k_not_enabled、duplicate_request 等错误都会附带恢复提示，使调用方无需解析说明文字即可分支处理并重试

开始使用

将以下内容添加到 MCP 客户端配置文件中，将 SEERR_BASE_URL 指向你自己的 Jellyseerr 或 Overseerr 实例，并提供其 API 密钥。

{
  "mcpServers": {
    "seerr-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/seerr-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SEERR_BASE_URL": "http://localhost:5055",
        "SEERR_API_KEY": "your-api-key"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "seerr-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/seerr-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SEERR_BASE_URL": "http://localhost:5055",
        "SEERR_API_KEY": "your-api-key"
      }
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 SEERR_BASE_URL=http://localhost:5055 SEERR_API_KEY=your-api-key bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 正在运行的 Jellyseerr 或 Overseerr 实例及其 API 密钥（Settings → General → API Key）。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/seerr-mcp-server.git

2. 进入目录：

cd seerr-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env — set SEERR_BASE_URL and SEERR_API_KEY

配置

所有配置都通过 src/config/server-config.ts 中的 Zod 模式在启动时验证。主要环境变量：

变量	描述	默认值
SEERR_BASE_URL	必需。 Jellyseerr/Overseerr 实例的基础 URL，例如 http://localhost:5055。服务会追加 /api/v1——不要添加 /api/v1 后缀，也不要添加尾部斜杠。	—
SEERR_API_KEY	必需。 Jellyseerr API 密钥（Settings → General → API Key）。作为 X-Api-Key 标头发送。	—
SEERR_REQUEST_TIMEOUT_MS	每次请求的 HTTP 超时时间，单位为毫秒。	15000
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_AUTH_MODE	认证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
MCP_SESSION_MODE	HTTP 会话模式；确认轮次需要解析为有状态模式。示例和 Docker 镜像设置为有状态；未设置时使用 auto，并解析为有状态。显式设置为无状态会导致启动失败。	auto
MCP_REQUEST_STATE_KEY	可选密钥，至少为 32 字节，在多个实例间共享，用于密封同意记录 ID。	—
OTEL_ENABLED	启用 OpenTelemetry 检测。	false
OTEL_EXPORTER_OTLP_ENDPOINT	用于跟踪和指标的 OTLP 基础端点；特定信号的端点会覆盖此值。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	可选启用日志导出的端点；基础端点不会启用日志导出。	—
LOG_TOOL_FAILURE_PAYLOADS	可选启用失败调用的参数/结果日志记录；脱敏依据键名匹配，因此自由格式值中的密钥可能会保留。	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t seerr-mcp-server .
docker run --rm \
  -e SEERR_BASE_URL=http://host.docker.internal:5055 \
  -e SEERR_API_KEY=your-api-key \
  -p 3010:3010 \
  seerr-mcp-server

Dockerfile 默认使用 HTTP 传输、有状态会话模式，并将日志写入 /var/log/seerr-mcp-server。默认会安装 OpenTelemetry 对等依赖项——构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口——注册六个工具和一个资源，并初始化 Seerr 服务。
src/config	使用 Zod 解析并验证服务专属的环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/services/seerr	Jellyseerr API 客户端、状态解码器，以及 PII/基础设施脱敏规范化器。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简而言之：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求级日志记录，使用 ctx.state 进行租户级存储
• 通过 src/mcp-server/*/definitions/index.ts 中的 barrel 文件注册新工具和资源
• 封装 Jellyseerr API：验证原始数据 → 规范化并脱敏为领域类型 → 返回输出模式；绝不捏造缺失字段，也绝不让操作员 PII 或路径进入输出

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。