内容
# Overseerr 的 FastMCP 服务器
用于与 Overseerr API 交互以管理电影和电视剧请求的 FastMCP 服务器，使用 `fastmcp` 库构建。
项目仓库：<a href="https://github.com/ptbsare/overseerr-mcp-server">https://github.com/ptbsare/overseerr-mcp-server</a>
## 组件
### 工具
服务器实现了以下工具与 Overseerr 交互：
- `overseerr_status`：获取 Overseerr 服务器的状态。
- `overseerr_movie_requests`：获取分页的电影请求列表。可选参数包括 `status`、`start_date`（格式：YYYY-MM-DDTHH:MM:SS.mmmZ）、`take`（默认为 7）和 `skip`（默认为 0）。
- `overseerr_tv_requests`：获取分页的电视剧请求列表。可选参数包括 `status`、`start_date`（格式：YYYY-MM-DDTHH:MM:SS.mmmZ）、`take`（默认为 7）和 `skip`（默认为 0）。
- `overseerr_request_movie_to_library`：使用 TMDB ID 将电影请求提交到特定库，代表特定用户。需要 `tmdb_id`、`library_name` 和 `user_display_name`。可用的库名称和用户显示名称（仅限唯一名称）在服务器启动时获取，并包含在工具的参数描述中。
- `overseerr_request_tv_to_library`：使用 TMDB ID 将电视剧请求提交到特定库，代表特定用户。需要 `tmdb_id`、`library_name` 和 `user_display_name`。可选参数为 `seasons`（整数列表）。可用的库名称和用户显示名称（仅限唯一名称）在服务器启动时获取，并包含在工具的参数描述中。
- `overseerr_search_media`：在 Overseerr 上搜索电影和电视剧。接受 `query` 和可选参数 `page`（默认为 1）。
- `overseerr_get_available_libraries`：从 Overseerr 获取配置的 Sonarr（电视剧）和 Radarr（电影）服务器 ID 和名称。
- `overseerr_get_users`：获取 Overseerr 中配置的所有用户，包括他们的 ID、用户名、电子邮件、显示名称等。
### 示例提示
首先建议您的 AI 助手（例如 Claude）使用 Overseerr 工具。然后，它可以在需要时调用适当的工具。
尝试以下提示：
- 获取我们的 Overseerr 服务器状态。
- 显示当前待处理的 5 个电影请求。
- 列出 2024-01-01 日所有可用的电视剧请求。
- 有哪些电影已被请求但尚未可用？
- 最近有哪些电视剧在我们的库中可用？
- 在 Overseerr 上搜索电影“Dune: Part Two”。
- Overseerr 中配置了哪些电影和电视剧库？
- 列出 Overseerr 中的所有用户。
- 请求 TMDB ID 为 693134 的电影，适用于用户 'John Doe'，在 'Movies HD' 库中。（使用 `user_display_name='John Doe'`，`library_name='Movies HD'`）
- 请求 TMDB ID 为 1396 的电视剧的第 1 和第 2 季，适用于用户 'Jane Smith'，在 'TV Shows 4K' 库中。（使用 `user_display_name='Jane Smith'`）
## 快速开始
### 前提条件
- `uv`（安装说明：<a href="https://github.com/astral-sh/uv">https://github.com/astral-sh/uv</a>）
- 运行中的 Overseerr 实例。
- 来自 Overseerr 实例的 API 密钥（设置 → API 密钥）。
### 使用 `uvx` 运行（推荐 - 无需安装）
您可以使用 `uvx` 直接从 git 仓库运行服务器 - 无需克隆或安装：
```bash
uvx --from git+https://github.com/ptbsare/overseerr-mcp-server.git overseerr-mcp-server
```
### Claude 桌面配置
将以下内容添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"overseerr-mcp-server": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/ptbsare/overseerr-mcp-server.git",
"overseerr-mcp-server"
],
"env": {
"OVERSEERR_API_KEY": "<your_api_key_here>",
"OVERSEERR_URL": "<your_overseerr_url>"
}
}
}
}
```
*将 `<your_api_key_here>` 和 `<your_overseerr_url>` 替换为您的实际 Overseerr API 密钥和 URL。*
### 环境变量
需要以下环境变量：
- `OVERSEERR_API_KEY`：您的 Overseerr API 密钥（在 Overseerr 设置 → API 密钥中找到）
- `OVERSEERR_URL`：您的 Overseerr 实例的 URL（例如 `http://localhost:5055`）
对于像 Claude Desktop 这样的客户端，请将这些添加到 `env` 字段中，如上所示。对于本地使用，您可以导出它们或使用 `.env` 文件：
```dotenv
OVERSEERR_API_KEY=your_api_key_here
OVERSEERR_URL=http://localhost:5055
```
### 本地开发安装
如果您更喜欢本地安装以进行开发：
```bash
git clone https://github.com/ptbsare/overseerr-mcp-server.git
cd overseerr-mcp-server
uv venv
source .venv/bin/activate # 在 Windows 上使用 `.venv\Scripts\activate`
uv pip install -e .
```
## 开发
### 设置
使用 `uv pip install -e .` 按照安装步骤进行可编辑安装。
### 依赖项
使用 `uv` 安装或同步依赖项：
```bash
uv sync
# 或
uv pip install -e .
```
### 调试
由于 MCP 服务器运行在 stdio 上，因此调试可能具有挑战性。
- **MCP Inspector:** 强烈推荐使用 <a href="https://github.com/modelcontextprotocol/inspector">MCP Inspector</a>。
启动它时指向您的服务器脚本：
```bash
# 使用 uvx（无需本地安装）
npx @modelcontextprotocol/inspector uvx --from git+https://github.com/ptbsare/overseerr-mcp-server.git overseerr-mcp-server
# 或使用 uv run（从本地项目目录）
npx @modelcontextprotocol/inspector uv run overseerr-mcp-server
```
在浏览器中访问 Inspector 提供的 URL。
- **日志记录：** 服务器将基本信息记录到 stdout/stderr。请检查运行 `uv run overseerr-mcp-server` 的终端。对于像 Claude Desktop 这样的客户端，请检查客户端的日志文件（例如 `~/Library/Logs/Claude/mcp-server-overseerr-mcp.log`，但名称可能会根据您的配置而有所不同）。
## 许可证
MIT
