🔧 MCP Server for ARR Stack

Model Context Protocol server для управления домашним медиастеком (Radarr, Sonarr, Prowlarr, Readarr, Lidarr, Seerr, Tautulli, Plex).

Позволяет локальным LLM моделям (Ollama, OpenWebUI и др.) напрямую взаимодействовать с вашими сервисами через стандартизированный MCP интерфейс.

---

📦 Возможности

Сервис	Возможности
Sonarr	Поиск/добавление/удаление сериалов, управление эпизодами, профили качества
Radarr	Поиск/добавление/удаление фильмов, управление коллекциями
Lidarr	Управление музыкой — артисты, альбомы, качество
Prowlarr	Поиск по индексам, управление трекерами, тестирование подключений
Readarr	Управление книгами и авторами
Seerr	Запросы медиаконтента, одобрение/отклонение запросов
Tautulli	Статистика просмотров, история, активность пользователей
Plex	Поиск в медиатеке, управление библиотеками, плейлисты

---

🚀 Быстрый старт (Docker)

1. Клонирование репозитория

git clone <your-repo-url> mcp-arr-stack
cd mcp-arr-stack

2. Настройка окружения

cp .env.example .env

Отредактируйте .env — укажите адреса и API ключи ваших сервисов:

# Sonarr (сериалы)
SONARR_HOST=http://sonarr:8989
SONARR_API_KEY=your_sonarr_api_key_here

# Radarr (фильмы)
RADARR_HOST=http://radarr:7878
RADARR_API_KEY=your_radarr_api_key_here

# Lidarr (музыка)
LIDARR_HOST=http://lidarr:8686
LIDARR_API_KEY=your_lidarr_api_key_here

# Prowlarr (поиск/индексы)
PROWLARR_HOST=http://prowlarr:9696
PROWLARR_API_KEY=your_prowlarr_api_key_here

# Seerr (запросы)
SEERR_HOST=http://seerr:5055
SEERR_API_KEY=your_seerr_api_key_here

# Tautulli (статистика Plex)
TAUTULLI_HOST=http://tautulli:8181
TAUTULLI_API_KEY=your_tautulli_api_key_here

# Plex Media Server
PLEX_HOST=http://plex:32400
PLEX_TOKEN=your_plex_token_here

Важно: Если сервис не нужен — просто оставьте его поля пустыми. Сервер автоматически отключит недоступные сервисы.

3. Запуск через Docker Compose

docker compose up -d --build

4. Проверка работы

# Просмотр логов
docker compose logs -f mcp-arr-stack

# Проверка статуса
docker compose ps

---

🌐 HTTP Transport

Сервер поддерживает Streamable HTTP транспорт для внешних MCP клиентов. Позволяет подключаться через HTTP/SSE вместо stdio.

Быстрый старт

# Через переменную окружения
MCP_TRANSPORT=http python -m src.server

# Через CLI флаг
python -m src.server --transport http

Конфигурация

Переменная	По умолчанию	Описание
MCP_TRANSPORT	stdio	Транспорт (stdio или http)
HTTP_HOST	0.0.0.0	Адрес привязки сервера
HTTP_PORT	8080	Порт сервера
HTTP_API_KEY	(пусто)	Bearer token для аутентификации клиентов
HTTP_CORS_ORIGINS	*	CORS разрешённые origins (через запятую или *)
HTTP_SSL_CERTFILE	(пусто)	Путь к SSL сертификату (опционально)
HTTP_SSL_KEYFILE	(пусто)	Путь к SSL приватному ключу (опционально)

Конфигурация клиента

Пример для MCP-совместимых клиентов:

{
  "mcpServers": {
    "arr-stack": {
      "url": "http://localhost:8080",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

Конечные точки (Endpoints)

Endpoint	Method	Описание
/	POST	MCP Streamable HTTP endpoint (JSON-RPC, SSE)
/health	GET	Health check — возвращает {"status": "ok"}

Docker Compose (HTTP режим)

# Запуск в режиме HTTP
docker compose up -d mcp-arr-stack-http

# Просмотр логов
docker compose logs -f mcp-arr-stack-http

---

🔌 Подключение к LLM

OpenWebUI

В настройках OpenWebUI добавьте MCP сервер:

{
  "mcp_servers": {
    "arr-stack": {
      "command": "docker",
      "args": [
        "exec", "-i", "mcp-arr-stack",
        "python", "-m", "src.server"
      ],
      "env": {}
    }
  }
}

Ollama (через MCP CLI)

# Запуск через docker exec
docker exec -i mcp-arr-stack python -m src.server

# Или подключите через MCP CLI
npx -y @modelcontextprotocol/cli --server "docker exec -i mcp-arr-stack python -m src.server"

Прямой запуск (для разработки)

# Создание виртуального окружения
python -m venv .venv
source .venv/bin/activate

# Установка зависимостей
pip install -r requirements.txt

# Запуск
python -m src.server

---

🛠 Доступные инструменты MCP

Sonarr (TV Series)

Инструмент	Описание
sonarr_search_series	Поиск сериалов по названию
sonarr_get_series	Получить детали сериала или список всех
sonarr_get_episodes	Список эпизодов с статусами
sonarr_add_series	Добавить новый сериал
sonarr_delete_series	Удалить сериал
sonarr_get_quality_profile	Профили качества
sonarr_get_root_folder	Доступные папки на диске
sonarr_get_series_status	Статус сериала (сколько эпизодов скачано)

Radarr (Movies)

Инструмент	Описание
radarr_search_movie	Поиск фильмов по названию
radarr_get_movies	Получить детали фильма или список всех
radarr_add_movie	Добавить новый фильм
radarr_delete_movie	Удалить фильм
radarr_get_quality_profile	Профили качества для фильмов
radarr_get_root_folder	Доступные папки на диске
radarr_get_movie_status	Статус фильма (размер, качество)

Prowlarr (Indexers)

Инструмент	Описание
prowlarr_search	Поиск по всем индексам
prowlarr_get_indexers	Список трекеров
prowlarr_test_indexers	Тестирование соединения со всеми трекерами
prowlarr_get_status	Общий статус Prowlarr

Seerr (Requests)

Инструмент	Описание
seerr_search	Поиск медиа через TMDB/TVDB
seerr_get_requests	Список запросов
seerr_request_media	Запрос фильма/сериала
seerr_approve	Одобрить запрос
seerr_reject	Отклонить запрос

Tautulli (Plex Statistics)

Инструмент	Описание
tautulli_get_activity	Текущая активность просмотров
tautulli_get_library_stats	Статистика медиатеки
tautulli_get_history	История просмотров
tautulli_get_user_stats	Статистика по пользователям
tautulli_get_recently_added	Недавно добавленный контент

Plex (Media Server)

Инструмент	Описание
plex_search	Поиск в медиатеке
plex_library_sections	Список библиотек
plex_recently_added	Недавно добавленное
plex_playlists	Плейлисты
plex_library	Элементы библиотеки
plex_get_status	Статус сервера Plex

Lidarr (Music)

Инструмент	Описание
lidarr_search_artist	Поиск артистов/альбомов
lidarr_get_artist	Детали артиста или список всех
lidarr_add_artist	Добавить нового артиста
lidarr_delete_artist	Удалить артиста

---

💡 Примеры использования

Для LLM (примеры промптов)

"Какие новые сезоны сериалов вышли на этой неделе?"
"Что мне посмотреть? Я люблю научную фантастику."
"Проверь, какие фильмы из моего списка ожидания ещё не скачались."
"Кто сейчас смотрит что-то дома?"
"Покажи статистику просмотров за последний месяц."
"Добавь сериал 'Black Mirror' в Sonarr."
"Какие трекеры в Prowlarr имеют проблемы?"

Пример ответа LLM с данными Sonarr

Пользователь: "Сколько эпизодов осталось посмотреть в Breaking Bad?"

LLM (через MCP):

1. Вызывает sonarr_get_series(title="Breaking Bad") → получает series_id=12345
2. Вызывает sonarr_get_episodes(series_id=12345) → получает список эпизодов
3. Анализирует статус каждого эпизода
4. Формулирует ответ: "В Breaking Bad 62 эпизода всего. Скачано 58, осталось 4."

---

📁 Структура проекта

mcp-arr-stack/
├── src/
│   ├── __init__.py
│   ├── server.py              # Основной MCP сервер
│   ├── http_server.py         # Streamable HTTP транспорт (ASGI, SSE)
│   ├── config.py              # Конфигурация (загрузка из .env)
│   ├── client.py              # HTTP клиенты для сервисов
│   ├── utils.py               # Утилиты (кэш, rate limiting)
│   └── tools/
│       ├── __init__.py
│       ├── sonarr_tools.py    # Инструменты Sonarr
│       ├── radarr_tools.py    # Инструменты Radarr
│       ├── lidarr_tools.py    # Инструменты Lidarr
│       ├── prowlarr_tools.py  # Инструменты Prowlarr
│       ├── readarr_tools.py   # Инструменты Readarr
│       ├── seerr_tools.py   # Инструменты Seerr
│       ├── tautulli_tools.py  # Инструменты Tautulli
│       └── plex_tools.py      # Инструменты Plex
├── tests/
│   ├── conftest.py            # Общие фикстуры
│   ├── __init__.py
│   ├── test_config.py         # Тесты конфигурации
│   ├── test_client.py         # Тесты клиентов
│   ├── test_utils.py          # Тесты утилит
│   ├── test_http_server.py    # Тесты HTTP транспорта
│   ├── test_sonarr_tools.py   # Тесты Sonarr
│   ├── test_radarr_tools.py   # Тесты Radarr
│   ├── test_lidarr_tools.py   # Тесты Lidarr
│   ├── test_readarr_tools.py  # Тесты Readarr
│   ├── test_seerr_tools.py    # Тесты Seerr
│   ├── test_tautulli_tools.py # Тесты Tautulli
│   └── test_plex_tools.py     # Тесты Plex
├── .env.example               # Шаблон переменных окружения
├── .gitignore
├── docker-compose.yml         # Docker Compose конфигурация
├── Dockerfile                 # Сборка Docker образа
├── requirements.txt           # Python зависимости
└── pyproject.toml             # Настройки проекта (pytest, black, ruff)

---

📚 API Reference

Полная документация по API всех сервисов доступна в docs/api-reference/:

Документ	Сервис
sonarr.md	Sonarr v3 API
radarr.md	Radarr v3 API
lidarr.md	Lidarr v1 API
prowlarr.md	Prowlarr v1 API
readarr.md	Readarr v1 API
seerr.md	Seerr v1 API
tautulli.md	Tautulli v2 API
plex.md	Plex API

---

🔒 Безопасность

• Все API ключи хранятся в .env файле (не коммитится в Git)
• Сервер работает от непривилегированного пользователя в Docker
• По умолчанию используется stdio транспорт — нет открытых портов
• HTTP транспорт поддерживает Bearer token аутентификацию (HTTP_API_KEY)
• CORS middleware для контроля доступа к HTTP endpoint'ам
• Rate limiting для защиты от перегрузки
• Graceful degradation — недоступный сервис не ломает остальные

---

🧪 Тестирование

# Установка зависимостей для разработки
pip install -r requirements.txt[dev]

# Запуск всех тестов
pytest

# С отчётом о покрытии
pytest --cov=src --cov-report=html

# Лinting и форматирование
ruff check src/ tests/
black --check src/ tests/

---

🛠 Troubleshooting

Сервис не подключается

1. Проверьте .env — правильные ли адреса и ключи
2. Убедитесь, что сервисы доступны из Docker сети:

   docker compose exec mcp-arr-stack ping sonarr
   

3. Проверьте логи:

   docker compose logs mcp-arr-stack
   

MCP инструменты не появляются в LLM

1. Убедитесь, что сервер запущен:

   docker compose ps
   

2. Проверьте подключение в интерфейсе вашего LLM клиента
3. Перезапустите сервер:

   docker compose restart mcp-arr-stack
   

Ошибки при сборке Docker

# Полная пересборка
docker compose build --no-cache

# Проверка сборки
docker compose config

---

📝 Лицензия

MIT License — см. файл LICENSE

---

🤝 Вклад

Принимаю PR и issues! Для больших изменений сначала создайте issue для обсуждения.

---

Создано с ❤️ для домашних медиастеков