mcp-arrstack

mcp-arrstack

MCP server that enables local LLMs to manage a home media stack including Radarr, Sonarr, Prowlarr, and others.

Category
访问服务器

README

🔧 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 для обсуждения.

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

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选