内容
# Prowlarr MCP 服务器
该服务器提供了一组工具，用于通过模型上下文协议（MCP）与 Prowlarr 实例交互。它是使用 FastMCP 构建的，允许管理索引器、应用程序、执行搜索、检查系统状态等，所有这些都基于 Prowlarr API v1。
## 设计原理
选择这些工具是为了暴露 Prowlarr 的核心功能，这些功能对于自动化、状态检查和通过 MCP 兼容客户端进行手动交互非常有用。选择基于 Prowlarr v1 OpenAPI 规范（`prowlarr-api.json`）和索引器及其关联应用程序管理的常见用例。
关键考虑因素：
- **全面覆盖**: 旨在覆盖主要的 Prowlarr 实体，如索引器、应用程序、系统状态、历史记录和搜索。
- **用户友好性**: 为复杂的输出提供人类可读的摘要，同时为编程使用保留完整的 JSON 数据。
- **配置**: 依赖环境变量来设置 Prowlarr API URL 和密钥，以及 MCP 服务器设置（传输、主机、端口、日志记录）以实现安全性和灵活性。
- **传输**: 默认使用 SSE（服务器发送事件）以实现远程访问和并发连接。
## 已实现的工具
1. `list_indexers()`: 检索所有已配置的索引器列表。
2. `get_indexer_details(id: int)`: 检索特定索引器的详细信息。
3. `search_releases(query: str, indexerIds: Optional[List[int]], categories: Optional[List[int]], type: Optional[str], limit: Optional[int], offset: Optional[int])`: 在索引器中搜索释放。
4. `test_indexer(id: int)`: 测试特定索引器的连接性和搜索能力。
5. `update_indexer(id: int, indexer_config: Dict[str, Any])`: 更新现有索引器的配置。
6. `list_applications()`: 检索与 Prowlarr 同步的应用程序列表。
7. `get_system_status()`: 检索 Prowlarr 系统状态和信息。
8. `get_indexer_categories()`: 检索默认索引器类别列表。
9. `get_history(page: Optional[int], pageSize: Optional[int], sortKey: Optional[str], sortDirection: Optional[str], eventType: Optional[List[int]], successful: Optional[bool], downloadId: Optional[str], indexerIds: Optional[List[int]])`: 检索 Prowlarr 的历史记录。
10. `test_all_indexers()`: 触发所有已配置索引器的测试并总结结果。
## 快速入门
### 先决条件
- Python 3.8+（推荐 Python 3.10+ 用于 `yarr-mcp` 项目）
- 一个运行中的 Prowlarr 实例（兼容 v1 API）。
- `uv`（推荐用于 `yarr-mcp` 项目中的包管理）。
### 安装
1. **克隆 `yarr-mcp` 仓库（如果尚未克隆）：**
```bash
git clone https://github.com/jmagar/yarr-mcp.git
cd yarr-mcp
```
2. **安装依赖项：**
依赖项（`fastmcp`、`httpx`、`python-dotenv` 等）由 `yarr-mcp` 主项目的 `pyproject.toml` 管理。
确保已激活主项目的虚拟环境（例如，使用 `uv venv`）：
```bash
# 从 yarr-mcp 项目根目录
source .venv/bin/activate
# 或在 Windows（Git Bash/WSL）上
# source .venv/Scripts/activate
```
3. **设置环境变量：**
在 `yarr-mcp` 项目根目录或 `src/prowlarr-mcp/` 目录（服务器特定的将覆盖项目根目录）中创建或更新 `.env` 文件。
参考 `src/prowlarr-mcp/.env.example` 获取所有可用选项。关键变量：
```env
PROWLARR_URL=http://your-prowlarr-host:9696
PROWLARR_API_KEY=your_prowlarr_api_key_here
PROWLARR_MCP_TRANSPORT=sse
PROWLARR_MCP_HOST=0.0.0.0
PROWLARR_MCP_PORT=6973
PROWLARR_MCP_LOG_LEVEL=INFO
PROWLARR_MCP_LOG_FILE=prowlarr_mcp.log
```
替换为实际的 Prowlarr 实例 URL 和 API 密钥。API 密钥可以在 Prowlarr 的设置 > 通用下找到。
### 运行服务器
确保项目的虚拟环境已激活。
从 `yarr-mcp` 项目根目录运行：
```bash
python src/prowlarr-mcp/prowlarr-mcp-server.py
```
服务器将启动，默认使用 SSE 传输，位于 `PROWLARR_MCP_HOST` 和 `PROWLARR_MCP_PORT`（默认为 `0.0.0.0:6973`）指定的主机和端口上。您应该会看到日志消息指示服务器已启动以及 SSE 端点，例如：
`INFO - ProwlarrMCPServer - Prowlarr MCP SSE 端点将在 http://0.0.0.0:6973/mcp 上可用`
## 客户端配置
### 克劳德桌面配置（用于 SSE）
如果服务器使用 SSE 传输（默认）运行，则可以创建一个 `MCP_CLIENT_CONFIG` JSON 文件来指示克劳德桌面（或类似客户端）如何连接。例如：
```json
{
"clients": [
{
"name": "ProwlarrMCP", // 或您喜欢的任何名称
"command": ["curl", "-N", "http://localhost:6973/mcp"],
"type": "sse",
"is_available": true
}
// 在此处添加其他 MCP 服务器配置
]
}
```
将此文件（例如 `mcp_config.json`）放在 MCP 客户端可以访问的位置，并配置客户端使用它（通常通过 `MCP_CLIENT_CONFIG` 环境变量指向此文件的路径）。
### STDIO 传输替代方案
如果需要使用 STDIO 传输，请在 `.env` 文件中设置 `PROWLARR_MCP_TRANSPORT=stdio`。然后 `MCP_CLIENT_CONFIG` 命令将是：
`["python", "/path/to/yarr-mcp/src/prowlarr-mcp/prowlarr-mcp-server.py"]`（使用脚本的绝对路径）。
## 使用示例
*（假设服务器正在运行并连接到您的 MCP 客户端）*
1. **列出所有已配置的索引器：**
```
@ProwlarrMCP list_indexers
```
*预期摘要： "找到 X 个索引器。 前几个： 名称1（ID：Y，已启用：True），... "*
2. **获取特定索引器的详细信息（例如，ID 10）：**
```
@ProwlarrMCP get_indexer_details id=10
```
*预期摘要： "检索了索引器 'IndexerName'（ID：10）的详细信息。"*
3. **搜索与“ubuntu”相关的释放，类别为 PC/ISO：**
*（类别 ID 可以使用 `get_indexer_categories` 并检查 Prowlarr UI/API 找到）*
```
@ProwlarrMCP search_releases query="ubuntu" categories=[4020]
```
*预期摘要： "为查询 'ubuntu' 找到 X 个释放。 前几个结果： ..."*
## 故障排除
1. **401 未授权错误**:
* 验证 `PROWLARR_URL` 和 `PROWLARR_API_KEY` 环境变量是否正确设置。
* 确保您的 Prowlarr 实例可通过网络访问，并且 API 访问已启用。
2. **连接问题（SSE）**：
* 确保 `prowlarr-mcp-server.py` 脚本正在运行并在正确的宿主/端口（默认 `0.0.0.0:6973/mcp`）上监听。
* 检查防火墙或网络配置。
* 验证客户端配置中的 URL 是否匹配。
3. **工具执行失败 / 参数类型错误**：
* 检查服务器日志（`src/prowlarr-mcp/prowlarr_mcp.log`，由 `PROWLARR_MCP_LOG_FILE` 配置）和控制台输出中的详细错误消息。
4. **`test_indexer` 报告 400 错误请求**：
* 这通常意味着 Prowlarr 自己发现了该索引器配置的验证问题。检查 Prowlarr UI。
## FastMCP 实现说明
- 服务器使用全局 `logger` 实例进行应用程序日志记录，配置为控制台和轮换文件输出（路径和级别可通过 `PROWLARR_MCP_LOG_FILE` 和 `PROWLARR_MCP_LOG_LEVEL` 配置）。
- 使用异步 HTTP 客户端（`httpx`）进行所有 API 调用到 Prowlarr。
- `_prowlarr_api_request` 中的错误处理尝试捕获 HTTP 状态错误和其他请求异常。
- 工具使用 FastMCP 中的 `@mcp.tool()` 装饰器定义。
- 服务器默认在 `/mcp` 路径上使用 SSE 传输。可以通过 `PROWLARR_MCP_TRANSPORT` 环境变量将其更改为 `stdio`。
- 服务器在 FastMCP 中注册的名称为 `Prowlarr MCP Server`。
- 参考 `prowlarr-api.json` 获取此服务器交互的 Prowlarr API v1 的 OpenAPI 规范。 # prowlarr-mcp
