@a1-x-tech/mcp-google-drive

v1.0.0

Published

5 days ago

MCP server for the Google Drive API — search, organize, upload, download, export, share and comment on Drive files. For Claude, Cursor, Codex and other AI clients.

0High
0Medium
0Low

gistrec

mcp model-context-protocol google google-drive drive files storage claude cursor codex

Google Drive MCP

English | Русский

A1 Google Drive MCP позволяет AI-приложению работать с вашим Google Drive на естественном языке. Можно найти файл, навести порядок в папках, загрузить и скачать содержимое, экспортировать документ в Markdown, поделиться им с нужными людьми — и держать корзину между вами и безвозвратным удалением.

Сервер работает с Google Drive API через ваш Google-аккаунт. Он одинаково видит «Мой диск» и общие диски, понимает «удалить» как обратимую корзину и явно показывает ограничения Drive API, а не создаёт впечатление, что с файлами можно сделать всё.

21 инструментов. Поиск и метаданные, папки и перемещение, загрузка и скачивание, экспорт Docs/Sheets/Slides, корзина, доступы и комментарии.
Подключение из диалога. Скажите «подключи Google Диск»: сервер проведёт через создание OAuth-клиента, поймает редирект Google на 127.0.0.1 с PKCE и сам сохранит токены — без конфигов и перезапуска.
Сначала корзина. «Удалить» означает обратимую корзину; безвозвратное удаление — сознательно отдельный инструмент, который нельзя выбрать случайно.
Документы остаются целыми. Docs, Sheets и Slides перемещаются, копируются, экспортируются и конвертируются как целые файлы — сервер никогда не редактирует текст внутри них.
Scope выбираете вы. Для чтения достаточно drive.readonly, drive.file ограничивает доступ файлами приложения; полный набор инструментов требует drive.

Начните с запроса, который только читает данные:

Найди в моём Drive документ с планом проекта, экспортируй его в Markdown и кратко перескажи.

Подключить сервер · Посмотреть сценарии · Открыть техническую документацию

Увидеть работу за минуту

Вы: Покажи содержимое папки «Договоры 2025», сначала новые.
Ассистент: Показывает файлы с типами, владельцами и датами изменения. Ничего не меняется.
Вы: Подготовь вложенную папку «Архив» и перенеси туда всё старше года.
Ассистент: Показывает папку, которую создаст, и файлы, которые перенесёт, затем запрашивает подтверждение.
Вы: Подтверждаю.
Ассистент: Создаёт папку и переносит файлы. Ничего не расшаривается, не отправляется в корзину и не удаляется, пока вы не попросите об этом отдельно.

Содержание

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

Нужны Node.js 20+ и Google-аккаунт. Учётные данные при установке не нужны: сервер подключается прямо в диалоге.

Добавьте сервер в AI-приложение.
Скажите «подключи Google Диск» — ассистент проведёт создание OAuth-клиента и выдачу доступа, не трогая конфиги.
Отправьте запрос, который только читает данные.

В desktop-приложении: откройте Settings → MCP servers, нажмите Add server, выберите STDIO и укажите команду npx -y @a1-x-tech/mcp-google-drive@latest вместе с переменными GOOGLE_DRIVE_CLIENT_ID, GOOGLE_DRIVE_CLIENT_SECRET и GOOGLE_DRIVE_REFRESH_TOKEN. Нажмите Save, затем Restart.

В IDE-расширении: откройте gear menu → MCP servers, нажмите Add server, выберите STDIO и укажите ту же команду и переменные окружения. Нажмите Save, затем Restart extension.

В командной строке:

codex mcp add google-drive \
  -- npx -y @a1-x-tech/mcp-google-drive@latest

codex mcp list

Документация Codex MCP

claude mcp add \
  --transport stdio --scope user google-drive \
  -- npx -y @a1-x-tech/mcp-google-drive@latest

claude mcp list

Документация Claude Code MCP

Актуальный официальный путь — Settings → Extensions. Для пользовательского desktop extension откройте Advanced settings → Extension Developer → Install Extension…, выберите файл .mcpb и следуйте подсказкам.

Этот репозиторий сейчас публикует npm-пакет со stdio и пока не содержит .mcpb. Поэтому используйте приведённый ниже JSON stdio-конфиг как fallback только в сборках Claude Desktop, где ещё поддерживается локальная конфигурация:

{
  "mcpServers": {
    "google-drive": {
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-drive@latest"]
    }
  }
}

В таких сборках сохраните его в ~/Library/Application Support/Claude/claude_desktop_config.json на macOS или %APPDATA%\Claude\claude_desktop_config.json на Windows.

Документация Claude Desktop MCP

Добавьте в ~/.cursor/mcp.json на macOS/Linux или %USERPROFILE%\.cursor\mcp.json на Windows:

{
  "mcpServers": {
    "google-drive": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-drive@latest"]
    }
  }
}

Документация Cursor MCP

Запустите MCP: Open User Configuration и добавьте:

{
  "servers": {
    "google-drive": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-drive@latest"]
    }
  }
}

Проверьте сервер командой MCP: List Servers.

Документация VS Code MCP

Что можно поручить

Найти и прочитать файлы

Найди таблицу с бюджетом за прошлый квартал и покажи, где она лежит и кто владелец.
Экспортируй бриф проекта в Markdown и кратко изложи открытые вопросы.
Скачай подписанный договор в PDF в мою папку с отчётами.

Навести порядок и перенести содержимое

Создай папку «Отчёты 2026» и перенеси в неё ежемесячные отчёты.
Загрузи эти заметки со встречи и преврати их в Google Doc.
Скопируй шаблон предложения и переименуй копию под нового клиента.

Поделиться и обсудить

Дай коллеге доступ к папке с правом комментировать и добавь сопроводительное сообщение к приглашению.
Покажи открытые комментарии в дизайн-документе и закрой те, что уже учтены.
Отзови у внешнего подрядчика доступ к архиву.

Убрать лишнее осознанно

Отправь устаревшие черновики в корзину — и восстанови тот, что удалён по ошибке.
Удали папку с тестовыми загрузками безвозвратно, когда я подтвержу.
Покажи содержимое корзины, пока оно не вычищено.

Как меняется ваш Drive

Всё в Drive — включая папки и объекты общих дисков — это файл с id. Имена не уникальны, поэтому инструменты работают по id, а дубли имён допустимы: перед созданием стоит поискать.
«Удалить» означает корзину: обратимо, Google вычищает её примерно через 30 дней. Безвозвратное удаление минует корзину, забирает с собой поддеревья папок и живёт в сознательно отдельном инструменте.
Google Docs, Sheets и Slides перемещаются, копируются, расшариваются, экспортируются и конвертируются как целые единицы. У сервера нет инструмента, который правит текст внутри документа или ячейки внутри таблицы.
Запись никогда не повторяется после неопределённого сбоя: повторы после сетевых и 5xx ошибок действуют только для чтения, поэтому копия, загрузка или новая папка не задвоятся у вас за спиной.

Встроенная загрузка ограничена 5 МБ (файлы крупнее идут через resumable-сессию в raw_request), экспорт — 10 МБ по ограничению Drive API. Комментарии, созданные через API, нельзя привязать к конкретному месту в тексте документа.

Что может измениться

| Операция | Что происходит | Граница подтверждения | |---|---|---| | Поиск, метаданные, скачивание, экспорт | Читает файлы и папки | Ничего не меняет | | Создание папки, копирование или загрузка | Добавляет файлы или заменяет содержимое | Меняет Drive | | Перемещение, переименование, обновление метаданных | Меняет расположение или свойства файла | Меняет файл | | Управление доступами | Выдаёт, меняет или отзывает доступ | Меняет, кто может открыть файл | | Управление комментариями | Создаёт, закрывает или удаляет ветки комментариев | Может уничтожить обсуждение | | Корзина и восстановление | Переносит файл в корзину или обратно | Обратимо ~30 дней | | Безвозвратное удаление | Стирает мимо корзины, включая поддеревья | Разрушительно | | Технический запрос API | Может вызвать метод API без отдельного инструмента | Потенциально разрушительно |

Как AI-приложение просит подтверждение, определяет само приложение. Сервер помечает операции чтения, записи и удаления, чтобы оно отличило проверку от рабочего изменения.

Как получить доступ

Google Drive требует OAuth 2.0: одного API-ключа недостаточно. Путей два, и первый не требует править конфигурационные файлы.

Подключение из диалога (рекомендуемый путь)

Скажите «подключи Google Диск», и ассистент пройдёт флоу вместе с вами:

setup_instructions выдаёт чек-лист: создать или выбрать проект Google Cloud, включить Google Drive API, настроить consent screen и создать OAuth-клиент типа Desktop app.
Скачайте JSON этого клиента («Download JSON») и передайте ассистенту путь к файлу — set_client сохранит его с правами только для владельца. Секрет через переписку не проходит.
start_login возвращает ссылку на согласие Google. Откройте её на этой же машине и подтвердите доступ: код возвращается на одноразовый слушатель 127.0.0.1 (PKCE), а не в чат.
finish_login меняет код на токены и кладёт их в ~/.config/mcp-google-drive/credentials.json (права 0600) и проверяет их реальным вызовом Google Drive API — так невключённый API ловится сразу.

Токены перечитываются на каждый вызов, поэтому подключение действует немедленно — перезапускать AI-приложение не нужно. auth_status показывает состояние, logout отзывает токен и удаляет его.

Переменные окружения (CI и автоматические установки)

Создайте или выберите проект Google Cloud и включите Google Drive API.
Настройте OAuth consent screen и создайте OAuth-клиент типа Desktop app.
Авторизуйте Google-аккаунт, с чьими файлами должен работать сервер. OAuth 2.0 Playground поможет получить refresh token, если включить Use your own OAuth credentials.
Запросите самый узкий scope, который покрывает вашу задачу:
| Scope | Что даёт | |---|---| | https://www.googleapis.com/auth/drive.readonly | Инструменты только для чтения: поиск, метаданные, скачивание, экспорт и список общих дисков. | | https://www.googleapis.com/auth/drive.file | Только файлы, созданные или открытые этим приложением, — достаточно для сценариев «загрузить и разложить» со своими файлами. | | https://www.googleapis.com/auth/drive | Полный набор инструментов: доступы, корзина, удаление и комментарии к любым файлам. |

Сервер использует тот scope, с которым выпущен refresh token; вызов за его пределами завершается ошибкой insufficientPermissions.

Refresh token OAuth-приложения в режиме Testing может истечь через семь дней. Для долгого доступа опубликуйте OAuth-приложение или используйте Internal-приложение в домене Workspace. Храните client secret и refresh token как пароли.

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

Все переменные необязательные — без единой из них сервер подключается из диалога.

| Переменная | Обязательна | Описание | |---|---|---| | GOOGLE_DRIVE_CLIENT_ID | Нет* | OAuth client ID. | | GOOGLE_DRIVE_CLIENT_SECRET | Нет* | OAuth client secret. | | GOOGLE_DRIVE_REFRESH_TOKEN | Нет* | OAuth refresh token. | | GOOGLE_DRIVE_ACCESS_TOKEN | Нет* | Короткоживущая (~1 час) альтернатива OAuth-тройке. | | GOOGLE_DRIVE_OAUTH_PORT | Нет | Фиксированный порт loopback-слушателя для входа из диалога; нужен при пробросе портов по SSH. | | GOOGLE_DRIVE_API_BASE | Нет | Переопределяет базовый URL Google APIs. | | GOOGLE_DRIVE_TIMEOUT_MS | Нет | Тайм-аут одного запроса; по умолчанию 60000 мс. | | GOOGLE_DRIVE_MAX_RETRIES | Нет | Повторы временных ошибок; по умолчанию 3. |

* Передайте OAuth-тройку или access token.

Совсем без учётных данных сервер всё равно стартует и завершает MCP-рукопожатие; первый вызов инструмента отвечает точным списком переменных, которые нужно задать, вместо мёртвого сервера.

Данные, лимиты и работа в фоне

Запросы идут в Google Drive. Локальный сервер обновляет OAuth-токены Google и вызывает Drive API. Анонимная телеметрия содержит ID установки, версию пакета, версии AI-клиента и платформы, а также имена инструментов — но не OAuth-токены, содержимое файлов, аргументы или промпты. Чтобы отключить её, задайте ASKADS_TELEMETRY=0.
У Google есть квоты и лимиты размеров. Загрузка через встроенный инструмент ограничена 5 МБ, экспорт — 10 МБ. При 429 сервер использует задержку; чтение также повторяется после сетевых и 5xx ошибок, а запись после неопределённой ошибки не повторяется.
С локальными файлами сервер осторожен. Скачивание сохраняет только по абсолютным путям и не перезаписывает существующий файл без явного разрешения; ответ прямо в диалоге ограничен 100 КБ текста.
Постоянного опроса нет. Сервер работает только при вызове; между запросами никто не следит за вашим Drive. Если AI-приложение поддерживает задания по расписанию, оно может периодически проверять изменения.

Техническая документация

Каталог MCP-возможностей — страницы по пользовательским задачам для каждого инструмента.
Все инструменты и параметры
Документация по разработке
Документация по публикации
Справочник Google Drive API

Поддержка

Нашли ошибку или не хватает сценария? Создайте issue или напишите в Telegram.