mcp-iadick: MCP-сервер для Яндекс Диска

Оглавление

Зачем это нужно
#

Я активно использую локальных ИИ-агентов вроде OpenCode и Hermes. Одна из задач — дать модели доступ к облаку: найти нужный документ, прочитать конфиг или лог, залить свежий бэкап проекта, скачать архив или сгенерировать временную ссылку.

Раньше для связки агентов с облаком я уже делал скилл для rclone в Hermes и подключал rclone для Яндекс Диска. Сам по себе rclone — эталонный швейцарский нож, но отдавать сырую консоль нейросетям…

Для цивилизованной работы нужен Model Context Protocol (MCP) вот и “родился” ЭМСИПИ ЯДИК.

Архитектура и инструменты
#

Под капотом сервер использует стандартный CLI rclone и настроенное подключение (remote) yandex:. Вся логика валидируется, отдаётся в строгом формате JSON-RPC и защищена от падений.

Сервер регистрирует 18 инструментов:

1. Навигация и метаданные
#

yandex_list_directory — просмотр содержимого папки с фильтрами (recursive, max_depth, dirs_only, files_only), размерами и датами модификации.
yandex_get_file_info — детальная информация о конкретном объекте.
yandex_search_files — рекурсивный поиск файлов по маске (например, *.pdf или *2026*).

2. Прямое чтение и запись (код, конфиги, логи, скрипты)
#

Не только чистый текст .txt, но и любые файлы, чьё содержимое передаётся строкой: исходный код, конфиги (JSON, YAML, TOML), шелл-скрипты, логи, разметка Markdown, SVG и т.д.

yandex_read_file — чтение содержимого файла с безопасными параметрами max_bytes и offset, чтобы не исчерпать лимит токенов контекста.
yandex_write_file — создание или перезапись файла с передачей содержимого строкой напрямую в rclone rcat.

3. Бинарные файлы (Base64) и ловушка сетевого MCP
#

Протокол MCP работает поверх JSON-RPC, поэтому прямая передача сырых байтов повреждает UTF-8 и ломает сессию. Но главное даже не в кодировке.

Когда MCP-сервер запущен локально на той же машине, что и агент (через stdio), у них общая файловая система. Инструмент yandex_upload_file(local_path=...) берёт локальный путь и заливает файл. Но как только сервер выносится в сеть (например, mcp-iadick крутится на сервере DietPi, а агент OpenCode запущен на вашем Маке), возникает фундаментальная проблема: файлы находятся на клиенте, а не на сервере.

Если агент на Маке передаст удалённому серверу путь со своего ноутбука (local_path: "/Users/user/photo.png"), сервер выдаст no such file or directory: он пытается найти файл на собственной файловой системе в Linux. Удалённый сервер физически не имеет доступа к диску вашего ноутбука.

Именно для решения этой проблемы сетевого использования я и реализовал режим Base64:

yandex_upload_base64 — клиентский агент на Маке сам читает файл со своего локального диска, переводит его байты в Base64 и передаёт прямо внутри тела запроса JSON-RPC. Удалённый сервер mcp-iadick на лету декодирует поток и закидывает файл в Яндекс Диск через rclone rcat. Никаких промежуточных копирований файлов по SCP/SSH на сервер больше не требуется! Поддерживаются как чистые строки, так и префиксы Data URL (data:image/png;base64,...).
yandex_download_base64 — читает бинарный файл с Диска и возвращает его в Base64 прямо в ответе агенту. Клиент принимает данные и сохраняет файл у себя на компьютере.

4. Прямой импорт из сети
#

yandex_upload_from_url — стримит внешний файл по HTTP/HTTPS прямой ссылке сразу на Яндекс Диск через rclone copyurl. Модели не нужно скачивать файл себе на машину и загружать повторно: облако забирает данные напрямую из интернета.

5. Синхронизация файлов сервера
#

Инструменты для файлов, которые физически находятся на диске хост-машины, где поднят сервис mcp-iadick:

yandex_upload_file — копирование файла с диска самого сервера на Диск.
yandex_download_file — выгрузка файла из Диска на локальный накопитель сервера.

6. Управление структурой
#

yandex_create_directory — создание папок.
yandex_copy_item и yandex_move_item — копирование, переименование и перемещение объектов.
yandex_delete_file и yandex_delete_directory — удаление файлов и каталогов (с флагом recursive).

7. Квота и ссылки
#

yandex_get_storage_info — проверка общего, занятого и свободного места на Диске.
yandex_create_public_link — создание публичной ссылки yadi.sk с возможностью задать срок действия (например, expire: "7d").
yandex_remove_public_link — отзыв публичного доступа.

Agent Skills
#

Сам по себе список функций — это лишь набор кнопок. Чтобы модель понимала, когда и как их нажимать, в репозитории tatarinovms/mcp-iadick подготовлены три готовых навыка по спецификации Agent Skills (разложены в .agents/skills/ и .opencode/skills/):

yandex-disk (Yandex Disk Management): базовая работа с файлами, соглашения по путям (без начального слэша), безопасное исследование директорий без перегрузки контекста.
yandex-disk-transfer (Yandex Disk File Transfer & Import): логика выбора транспорта: когда читать текст, когда кодировать в Base64 для передачи с клиента, а когда использовать прямой сетевой copyurl.
yandex-disk-backup (Yandex Disk Backup & Snapshot): автоматический пайплайн резервного копирования. Перед началом агент опрашивает yandex_get_storage_info на наличие свободного места, создаёт структурированный каталог Backups/<проект>/YYYY-MM-DD, заливает архив, проверяет его целостность через yandex_get_file_info и отдаёт временную ссылку yadi.sk.

Установка и подготовка
#

На сервере или рабочей машине должен быть настроен rclone. Проверяем подключение к Яндекс Диску:

rclone lsd yandex:

Если список папок отображается — всё в порядке. Дальше есть два варианта: взять готовый собранный бинарник или скомпилировать из исходников.

Вариант 1. Готовые бинарники (GitHub Releases)
#

Если нет Go и не хочется его ставить, берём готовый архив со страницы Releases на GitHub и распаковываем одной командой:

# Для Linux ARM64 (DietPi / Raspberry Pi):
curl -sL https://github.com/tatarinovms/mcp-iadick/releases/latest/download/mcp-iadick-linux-arm64.tar.gz | tar -xz -C /usr/local/bin/

# Для Linux AMD64 (DietPi / Raspberry Pi):
curl -sL https://github.com/tatarinovms/mcp-iadick/releases/latest/download/mcp-iadick-linux-amd64.tar.gz | tar -xz -C /usr/local/bin/

# Для macOS Apple Silicon (M1/M2/M3/M4):
curl -sL https://github.com/tatarinovms/mcp-iadick/releases/latest/download/mcp-iadick-darwin-arm64.tar.gz | tar -xz -C /usr/local/bin/

Вариант 2. Сборка из исходников
#

Если в системе уже установлен Go (1.23+), компиляция занимает пару секунд:

git clone https://github.com/tatarinovms/mcp-iadick.git /opt/mcp-iadick
cd /opt/mcp-iadick
go build -o /usr/local/bin/mcp-iadick ./cmd/mcp-iadick

Режимы работы: локальный (stdio) и сетевой (HTTP / Dual)
#

Утилита mcp-iadick поддерживает два принципиально разных режима работы:

1. Локальный режим без сети (`-transport stdio`)
#

Сервер запускается локально на той же машине, где работает AI-агент (macOS или Linux).

Как работает: клиент сам порождает дочерний процесс mcp-iadick и обменивается с ним сообщениями через стандартные потоки ввода/вывода (stdin/stdout).
Плюсы: вообще не используются сетевые порты, не нужны права суперпользователя, не нужны фоновые демоны или systemd.
Это режим по умолчанию.

2. Сетевой режим (`-transport dual` или `-transport http`)
#

Сервер работает постоянно в фоне на отдельной машине (домашний сервер, DietPi, VPS), а клиенты обращаются к нему по сети.

Streamable HTTP (-transport http -addr :8123): современный стандарт MCP для OpenCode v2 (POST /mcp).
Legacy SSE (-transport sse -addr :8123): классический двухэтапный протокол для клиентов вроде Hermes (GET /sse + POST /message).
Универсальный режим Dual (-transport dual -addr :8123): поднимает оба эндпоинта на одном порту — универсальное решение для сервера в домашней сети.

Автозапуск на сервере DietPi / Linux (systemd)
#

Note

Этот шаг нужен только для сетевого режима, когда mcp-iadick крутится как фоновый сервис на сервере. Если вы работаете локально на своём ПК через stdio, этот раздел можно пропустить.

Создаём юнит /etc/systemd/system/mcp-iadick.service:

[Unit]
Description=Yandex Disk MCP Server
After=network.target

[Service]
Type=simple
User=root
Environment=RCLONE_REMOTE=yandex
ExecStart=/usr/local/bin/mcp-iadick -transport dual -addr :8123 -base-url http://<ip-сервера>:8123
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Запуск от пользователя, у которого в ~/.config/rclone/rclone.conf настроен токен Яндекса.

Активируем и запускаем:

systemctl daemon-reload
systemctl enable --now mcp-iadick.service
systemctl status mcp-iadick.service

Настройка подключения в OpenCode v2
#

OpenCode поддерживает как локальный запуск через stdio, так и сетевой доступ к удалённому серверу.

Вариант 1. Локальный запуск (stdio) — без сети и портов
#

Самый простой и надёжный способ для работы прямо на рабочей машине (macOS или Linux). OpenCode сам запускает бинарник при старте сессии.

Прописываем в ~/.config/opencode/opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "yandex-disk": {
        "type": "local",
        "command": ["/usr/local/bin/mcp-iadick"],
        "args": ["-transport", "stdio"],
        "environment": {
          "RCLONE_REMOTE": "yandex"
        }
      }
    }
  },
  "permission": {
    "yandex_*": "allow"
  }
}

Или через команду CLI:

opencode mcp add yandex-disk -- /usr/local/bin/mcp-iadick -transport stdio

Вариант 2. Сетевое подключение к серверу (Streamable HTTP)
#

Если mcp-iadick запущен как фоновый демон на DietPi:

В конфигурации ~/.config/opencode/opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "yandex-disk": {
        "type": "remote",
        "url": "http://<ip-сервера>:8123/mcp",
        "enabled": true
      }
    }
  },
  "permission": {
    "yandex_*": "allow"
  }
}

Или через команду CLI:

opencode mcp add yandex-disk --url http://<ip-сервера>:8123/mcp

Tip

Директива "permission": { "yandex_*": "allow" } в обоих вариантах избавляет от необходимости вручную подтверждать вызовы инструментов при каждом обращении агента к диску.

Проверяем статус подключения:

opencode mcp list

В выводе отобразится сервер yandex-disk в статусе connected со всеми 18 инструментами.

Подключение в Hermes (SSE)
#

Если клиент работает только по классическому протоколу Server-Sent Events, в ~/.hermes/config.yaml указываем SSE-эндпоинт удалённого сервера:

mcp_servers:
  yandex-disk:
    url: http://<ip-сервера>:8123/sse
    connect_timeout: 60
    timeout: 120

Примеры живых сценариев
#

Благодаря поддержке Agent Skills, агенту не нужно объяснять низкоуровневые нюансы MCP-вызовов — модель автоматически активирует подходящий навык по описанию вашей задачи (или по прямому обращению через @навык).

1. Навигация и работа с документами (навык `yandex-disk`)
#

Навык активируется при запросах исследования облака, поиска файлов, чтения текстового содержимого и проверки квоты.

Команда агенту:
«Проверь свободное место на Яндекс Диске, найди в папке Docs все заметки по маске *report*2026* и выведи первые 500 байт из самого свежего файла».
(или прямой вызов: @yandex-disk найди отчеты за 2026 год в папке Docs)
Цепочка вызовов MCP:
1. Агент следует правилу не забивать контекст и сначала проверяет квоту: yandex_get_storage_info().
2. Пути формулируются без ведущего слэша, запускается точечный поиск: yandex_search_files(path: "Docs", pattern: "*report*2026*").
3. Для найденного документа запрашиваются метаданные: yandex_get_file_info(path: "Docs/report-q3.md").
4. Содержимое читается с ограничением токенов: yandex_read_file(path: "Docs/report-q3.md", max_bytes: 500).

2. Загрузка бинарников и импорт по URL (навык `yandex-disk-transfer`)
#

Срабатывает при передаче бинарных файлов (картинки, архивы, PDF) с клиентского компьютера на удалённый MCP-сервер, а также при прямом скачивании из сети.

Команда агенту (локальный бинарный файл через Base64):
«Загрузи с моего ноутбука локальную картинку ./assets/architecture.png на Яндекс Диск в папку Designs/Architecture».
(или: @yandex-disk-transfer загрузи локальный файл ./assets/architecture.png на Диск)
Цепочка вызовов MCP:
1. Скилл предотвращает ошибку удалённого сервера no such file or directory: агент знает, что удалённый сервер не имеет доступа к файлам клиентского ноутбука.
2. Клиентский агент читает локальный файл и переводит байты в Base64.
3. Создаёт целевой каталог: yandex_create_directory(path: "Designs/Architecture").
4. Заливает данные вызовом yandex_upload_base64(remote_path: "Designs/Architecture/architecture.png", content_base64: "...").
Команда агенту (прямой сетевой импорт без сохранения на диск):
«Скачай релизный архив с GitHub по ссылке https://github.com/tatarinovms/mcp-iadick/releases/latest/download/mcp-iadick-linux-arm64.tar.gz напрямую в папку Distr на Яндекс Диске».
Цепочка вызовов MCP: Агент вызывает yandex_upload_from_url(url: "...", remote_path: "Distr/mcp-iadick-linux-arm64.tar.gz") — облако забирает файл из интернета сразу на Диск через rclone copyurl.

3. Резервное копирование и снапшот проекта (навык `yandex-disk-backup`)
#

Активирует регламентный процесс бэкапа: pre-flight проверка квоты, структурирование папок по дате ISO 8601, архивация, проверка целостности и выпуск временной публичной ссылки.

Команда агенту:
«Сделай резервную копию конфигураций проекта на Яндекс Диск в папку Backups, проверь квоту и сгенерируй ссылку на скачивание на 3 дня».
(или: @yandex-disk-backup сделай бэкап конфигов проекта и дай ссылку на 3 дня)
Цепочка вызовов MCP:
1. Pre-flight проверка: агент опрашивает yandex_get_storage_info() и убеждается в наличии свободного места.
2. Иерархия каталогов: создаёт папку с текущей датой: yandex_create_directory(path: "Backups/my-project/2026-10-09").
3. Загрузка: отправляет архив на Диск (через yandex_upload_base64 при удалённом MCP или yandex_upload_file при локальном).
4. Верификация: проверяет факт загрузки и размер архива через yandex_get_file_info.
5. Публикация: создаёт ссылку yandex_create_public_link(path: "Backups/my-project/2026-10-09/config.zip", expire: "3d") и возвращает пользователю готовый URL yadi.sk.

Итог
#

Помните! Вы выликолепны, кто бы и чтобы не говорил!

Все исходные коды сервера и готовые навыки открыты в репозитории tatarinovms/mcp-iadick на GitHub.

Зачем это нужно#

Архитектура и инструменты#

1. Навигация и метаданные#

2. Прямое чтение и запись (код, конфиги, логи, скрипты)#

3. Бинарные файлы (Base64) и ловушка сетевого MCP#

4. Прямой импорт из сети#

5. Синхронизация файлов сервера#

6. Управление структурой#

7. Квота и ссылки#

Agent Skills#

Установка и подготовка#

Вариант 1. Готовые бинарники (GitHub Releases)#

Вариант 2. Сборка из исходников#

Режимы работы: локальный (stdio) и сетевой (HTTP / Dual)#

1. Локальный режим без сети (-transport stdio)#

2. Сетевой режим (-transport dual или -transport http)#

Автозапуск на сервере DietPi / Linux (systemd)#

Настройка подключения в OpenCode v2#

Вариант 1. Локальный запуск (stdio) — без сети и портов#

Вариант 2. Сетевое подключение к серверу (Streamable HTTP)#

Подключение в Hermes (SSE)#

Примеры живых сценариев#

1. Навигация и работа с документами (навык yandex-disk)#

2. Загрузка бинарников и импорт по URL (навык yandex-disk-transfer)#

3. Резервное копирование и снапшот проекта (навык yandex-disk-backup)#

Итог#

Related