mcp-synology

MCP-сервер для устройств Synology NAS. Предоставляет функциональность API Synology DSM в виде инструментов MCP, которые может использовать Claude.

Миграция с synology-mcp

Если вы обновляетесь с synology-mcp (версии 0.3.x или более ранней), пакет был переименован. Скрипт миграции автоматически обрабатывает конфигурацию, состояние, записи в связке ключей и конфигурацию Claude Desktop:

# Download and run the migration script
curl -O https://raw.githubusercontent.com/cmeans/mcp-synology/main/scripts/migrate-from-synology-mcp.py
python migrate-from-synology-mcp.py          # dry run — preview changes
python migrate-from-synology-mcp.py --apply  # apply changes

Скрипт переносит:

• Каталог конфигурации (~/.config/synology-mcp/ → ~/.config/mcp-synology/)

• Каталог состояния (~/.local/state/synology-mcp/ → ~/.local/state/mcp-synology/)

• Учетные данные из связки ключей

• Файл claude_desktop_config.json для Claude Desktop (обновляет команду и пути)

Полную информацию о критических изменениях см. в CHANGELOG.md.

Поддерживаемые модули

File Station

Просмотр, поиск, передача и управление файлами на вашем NAS. 14 инструментов, разделенных на два уровня прав доступа:

• READ (Чтение) — list_shares, list_files, list_recycle_bin, search_files, get_file_info, get_dir_size, download_file

• WRITE (Запись) — create_folder, rename, copy_files, move_files, delete_files, restore_from_recycle_bin, upload_file

System

Мониторинг состояния и использования ресурсов NAS. 2 инструмента только для чтения:

• get_system_info — модель, версия прошивки, ОЗУ, температура, время работы (доступно для всех пользователей)

• get_resource_usage — текущая нагрузка на ЦП, использование памяти, ввод-вывод диска, пропускная способность сети (требуется учетная запись администратора)

Возможности

• Интерактивная настройка — пошаговая конфигурация, которая создает файл настроек, сохраняет учетные данные, обрабатывает 2FA и выдает фрагмент кода для Claude Desktop

• Уровни прав доступа — READ или WRITE для каждого модуля, проверяются при регистрации инструмента

• Поддержка 2FA — автоматическое обнаружение; создание токена устройства с автоматической тихой повторной аутентификацией

• Безопасные учетные данные — интеграция со связкой ключей ОС, которая прозрачно работает в macOS, Windows и Linux (включая Claude Desktop). См. docs/credentials.md.

• Multi-NAS — управление несколькими устройствами NAS с отдельными конфигурациями, учетными данными и состояниями

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

1. Запуск настройки

uvx mcp-synology setup

Требуется uv. uvx автоматически загружает и запускает последнюю версию — отдельный шаг установки не требуется.

В процессе настройки будут запрошены хост вашего NAS, учетные данные и предпочтения. Если для вашей учетной записи включена 2FA, потребуется ввести OTP-код, после чего будет сохранен токен устройства для автоматического входа в будущем.

В конце будет выведен JSON-фрагмент для Claude Desktop, готовый к копированию.

2. Добавление в Claude Desktop

Скопируйте фрагмент из настройки в ваш claude_desktop_config.json и перезапустите Claude Desktop. Он будет выглядеть примерно так:

{
  "mcpServers": {
    "synology-nas": {
      "command": "uvx",
      "args": ["mcp-synology", "serve", "--config", "~/.config/mcp-synology/nas.yaml"]
    }
  }
}

Имя файла конфигурации (например, nas.yaml) также служит естественным идентификатором для подключения — вы можете назвать его в соответствии с вашим NAS (например, home-nas.yaml, office-nas.yaml).

В Linux сервер автоматически определяет сессионный сокет D-Bus для доступа к связке ключей. Если автоматическое определение не сработало, добавьте "env": {"DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/<uid>/bus"} в конфигурацию Claude Desktop. Команда настройки включает это в сгенерированный фрагмент.

3. Проверка

uvx mcp-synology check                # Validates credentials work
uvx mcp-synology setup --list         # Shows all configured NAS instances

Альтернатива: глобальная установка

Если вы предпочитаете постоянную установку (избегает загрузки при каждом вызове):

uv tool install mcp-synology
mcp-synology setup
mcp-synology check

Альтернатива: режим только через переменные окружения

Файл конфигурации не нужен, если установлена переменная SYNOLOGY_HOST. Это полезно для Docker или CI-сред:

{
  "mcpServers": {
    "synology": {
      "command": "uvx",
      "args": ["mcp-synology", "serve"],
      "env": {
        "SYNOLOGY_HOST": "192.168.1.100",
        "SYNOLOGY_USERNAME": "your_user",
        "SYNOLOGY_PASSWORD": "your_password"
      }
    }
  }
}

Или через CLI:

SYNOLOGY_HOST=192.168.1.100 uvx mcp-synology check

Поддержка 2FA

mcp-synology полностью поддерживает учетные записи DSM с двухфакторной аутентификацией. Она определяется автоматически — вам не нужно ничего настраивать:

1. Инициализация — mcp-synology setup обнаруживает 2FA, запрашивает OTP-код и сохраняет токен устройства в связке ключей

2. Тихая повторная аутентификация — последующие входы автоматически используют токен устройства (без запросов OTP)

3. Для каждого экземпляра — каждая конфигурация NAS получает свой токен устройства, поэтому смешанные настройки (с 2FA и без) работают корректно

Токены устройств сохраняются до тех пор, пока вы явно не отзовете их в DSM (Личные > Безопасность > Активность входа). Они не истекают сами по себе. Если токен отозван, запустите mcp-synology setup снова для повторной инициализации.

Связка ключей и учетные данные

Учетные данные хранятся в связке ключей ОС и используются прозрачно:

Порядок разрешения учетных данных: переменные окружения > файл конфигурации > связка ключей. Явные источники переопределяют неявные значения по умолчанию.

Для сред без связки ключей (Docker, CI) используйте переменные окружения или укажите учетные данные прямо в файле конфигурации.

См. docs/credentials.md для получения информации об именах сервисов связки ключей, настройке нескольких NAS и способах просмотра/удаления сохраненных учетных данных.

Обновления

mcp-synology проверяет наличие обновлений и уведомляет вас в диалоге Claude Desktop — первый ответ инструмента в каждой сессии будет содержать уведомление, если на PyPI доступна более новая версия.

Для управления обновлениями через CLI:

mcp-synology --check-update                 # Check for a newer version
mcp-synology --auto-upgrade enable           # Auto-upgrade on each interactive run
mcp-synology --revert                        # Roll back to previous version
mcp-synology --revert 0.1.0                  # Roll back to a specific version

Чтобы отключить уведомления об обновлениях, добавьте в вашу конфигурацию (на верхнем уровне):

# ~/.config/mcp-synology/config.yaml
check_for_updates: false

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

Интерактивная настройка создает файл конфигурации за вас. Для ручной настройки или расширенных параметров см. examples/:

• config-minimal.yaml — максимально простая конфигурация

• config-power-user.yaml — HTTPS, пользовательские тайм-ауты, логирование, инструкции

• config-docker.yaml — конфигурация через переменные окружения

Multi-NAS

Каждый NAS получает свой файл конфигурации, учетные данные и запись в Claude Desktop. Имя файла конфигурации служит естественным идентификатором (например, home-nas.yaml, media-server.yaml).

Установите alias, чтобы дать Claude отображаемое имя для подключения:

# ~/.config/mcp-synology/home-nas.yaml
alias: HomeNAS

Псевдоним появляется в имени MCP-сервера (например, synology-HomeNAS), чтобы Claude знал, к какому NAS он обращается.

Пользовательские инструкции

Пользовательские инструкции позволяют формировать то, как Claude взаимодействует с инструментами вашего NAS. Это полезно, когда:

• Несколько подключений к NAS — укажите Claude, какое подключение предпочесть для разных задач ("используй это для медиа, используй admin для операций между пользователями")

• Правила безопасности — добавьте правила, такие как "всегда подтверждай перед удалением" или "никогда не трогай /Backups"

• Контекст — объясните, что находится на NAS ("это медиа-сервер, в /video наша библиотека, отсортированная по жанрам")

Добавление контекста — custom_instructions добавляются перед встроенной подсказкой (более высокий приоритет):

# ~/.config/mcp-synology/config.yaml
custom_instructions: |
  This is the admin NAS with elevated privileges.
  Prefer this connection for file operations requiring cross-user access.
  Never delete files from /Backups without explicit confirmation.

Полный контроль — instructions_file полностью заменяет встроенную подсказку. Скопируйте встроенный server.md в качестве отправной точки:

# ~/.config/mcp-synology/config.yaml
instructions_file: ~/.config/mcp-synology/my-instructions.md

Оба варианта поддерживают переменные шаблона: {display_name}, {instance_id}, {host}, {port}.

Отладка

Два способа включить отладочное логирование:

mcp-synology check --verbose                          # --verbose flag on setup/check
SYNOLOGY_LOG_LEVEL=debug mcp-synology serve           # env var, works for all commands

Или установите это постоянно в файле конфигурации:

# ~/.config/mcp-synology/config.yaml
logging:
  level: debug
  file: ~/.local/state/mcp-synology/nas/server.log  # optional, logs to stderr by default

Вывод отладки включает каждый запрос/ответ API DSM (пароли скрыты), шаги разрешения учетных данных, обнаружение конфигурации, согласование версий и решения о регистрации модулей.

Участие в разработке

См. DEVELOPMENT.md для команд сборки, тестирования, настройки интеграционных тестов и проектной документации.

Благодарности

Этот проект был создан с использованием подхода Spec-First Coding (сначала спецификации) — модели сотрудничества человека и ИИ, где проектирование предшествует реализации, а спецификации являются контрактом между ними.

В отличие от "vibe coding", где вы описываете, что хотите, и позволяете ИИ генерировать код на лету, spec-first coding рассматривает проектирование как отдельный, осознанный этап. Четыре спецификации в docs/specs/ были разработаны в ходе длительного обсуждения — изучения компромиссов, отклонения альтернатив и документирования решений с обоснованием. Затем реализация использовала спецификации как единственный источник истины на протяжении 11 этапов сборки.

Живое тестирование на реальном оборудовании выявило поведение, которое спецификации не могли предвидеть (особенности API DSM, ограничение скорости службы поиска, несовместимость форматов версий). Эти открытия задокументированы в CLAUDE.md и коде, который является авторитетным источником в случае расхождения со спецификациями.

Лицензия

Apache 2.0