gdrive-write-mcp

MCP-сервер, который даёт ИИ-ассистентам реальный доступ на запись в Google Drive — обновление содержимого на месте, добавление в конец и замену по совпадению, сохраняя ID файла, настройки доступа, комментарии и историю версий.

Проблема

Большинство интеграций Google Drive для ИИ-ассистентов — это «чтение плюс создание». Они умеют искать файлы, читать их, создавать новые и перемещать старые в корзину — но у них нет способа изменить содержимое уже существующего файла.

Звучит как небольшой пробел. Это не так. Без записи на месте «отредактируй этот документ» превращается в:

1. Прочитать файл.

2. Создать новый файл с исправленным содержимым.

3. Удалить старый.

В результате технически текст правильный, а всё остальное — нет:

gdrive-write-mcp закрывает этот пробел. Drive API от Google всегда поддерживал обновление содержимого на месте; это небольшой узкоспециализированный сервер, который открывает эти возможности через MCP.

Related MCP server: Google Docs MCP Server

Что он делает

Редактирование

• replace_in_file — замена по точному совпадению. Инструмент, к которому стоит обращаться по умолчанию: не требует повторной отправки всего документа и не может случайно потерять содержимое, о котором не упоминалось.

• append_to_file / prepend_to_file — добавление к любому из концов, без повторной отправки уже имеющегося. Создан для логов, журналов и списков изменений.

• update_file_content — замена всего документа. По своей природе разрушителен, поэтому в документации для модели описан как крайняя мера, а не вариант по умолчанию.

Чтение

• read_file — содержимое плюс revisionToken, используемый для безопасной следующей записи.

• get_file_metadata — проверка, не переместился ли файл, без его загрузки.

• search_files — синтаксис запросов Drive, чтобы имя файла можно было превратить в ID, который нужен инструментам записи.

• list_revisions — история, которую сохраняет редактирование на месте.

Создание

• create_file — для действительно новых документов, с опциональной конвертацией в нативный Google Doc или Sheet.

Две вещи, которые он делает правильно

1. Конкурентные правки отклоняются, а не молча проглатываются

Сценарий отказа наивного инструмента записи тих и дорог: вы читаете документ, тридцать секунд думаете и записываете его обратно — затирая абзац, который тем временем добавил коллега. Никто не получает ошибку. Никто не замечает, пока через несколько дней не обнаружится пропавший абзац.

Каждое чтение здесь возвращает revisionToken, и каждая запись принимает его:

read_file(fileId)                    → revisionToken: "0B1a2…"
update_file_content(fileId, content, expectedRevisionToken: "0B1a2…")

Если файл изменился, запись отклоняется с ошибкой, которая точно говорит модели, что делать — перечитать, применить заново, записать снова — вместо голого 409. Целевые инструменты (replace_in_file, append_to_file, prepend_to_file) читают и пишут в рамках одного вызова, поэтому защита срабатывает автоматически, и вам никогда не приходится работать с токеном вручную.

Drive предоставляет headRevisionId только для файлов с реальным бинарным содержимым — у нативных Google-документов и таблиц его нет, а именно там конкурентное редактирование человеком наиболее вероятно, ведь это те файлы, которые кто-то держит открытыми во вкладке браузера. Для таких файлов токен переключается на modifiedTime, так что нативные файлы тоже защищены.

2. Нативные файлы Google обрабатываются честно

Drive хранит два очень разных вида сущностей, и их смешение — самый частый источник багов в интеграциях с Drive:

• Загруженные файлы (text/markdown, application/pdf, …) — байты на входе, байты на выходе.

• Нативные файлы редакторов (application/vnd.google-apps.document, …) — не имеют собственных байтов. Читаются экспортом в конкретный формат; записываются загрузкой формата, который Drive конвертирует обратно при приёме.

Этот сервер определяет, с каким типом имеет дело, и маршрутизирует соответственно. Документы экспортируются в markdown, а не в обычный текст, специально для того, чтобы цикл «прочитать — изменить — записать» сохранял заголовки, списки и выделение, а не молча сплющивал документ. Бинарные файлы кодируются в base64, а не декодируются как UTF-8, так что PDF никогда не будет испорчен прохождением через текстовый инструмент.

Установка

git clone https://github.com/anaborne/gdrive-write-mcp.git
cd gdrive-write-mcp
npm install
npm run build

Требуется Node 18 или новее.

Настройка

Шаг 1 — Создайте OAuth-клиент Google

1. Откройте Google Cloud Console и создайте проект (или выберите существующий).

2. Включите Google Drive API: APIs & Services → Library → Google Drive API → Enable.

3. Настройте экран согласия OAuth: APIs & Services → OAuth consent screen. Выберите External, заполните обязательные поля и добавьте свой аккаунт Google в раздел Test users. (Пока приложение в режиме «Testing», авторизоваться могут только перечисленные тестовые пользователи — что вам и нужно для личного инструмента.)

4. Создайте учётные данные: APIs & Services → Credentials → Create Credentials → OAuth client ID → Desktop app.

5. Скопируйте Client ID и Client secret.

Шаг 2 — Получите refresh-токен

cp .env.example .env
# put GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env
npm run authorize

Это запускает одноразовый процесс согласия на http://localhost:4181 и выводит refresh-токен. Добавьте его в .env:

GOOGLE_CLIENT_ID=1234567890-abcdef.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-…
GOOGLE_REFRESH_TOKEN=1//0g…

Шаг 3 — Укажите вашему MCP-клиенту на сервер

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "gdrive-write": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-write-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "…",
        "GOOGLE_CLIENT_SECRET": "…",
        "GOOGLE_REFRESH_TOKEN": "…"
      }
    }
  }
}

Claude Code:

claude mcp add gdrive-write \
  --env GOOGLE_CLIENT_ID=… \
  --env GOOGLE_CLIENT_SECRET=… \
  --env GOOGLE_REFRESH_TOKEN=… \
  -- node /absolute/path/to/gdrive-write-mcp/dist/index.js

Всё остальное — сервер говорит по MCP через stdio. Запустите node dist/index.js как подпроцесс с этими тремя переменными окружения.

Шаг 4 — Проверьте, что всё работает

npm run verify

Это запускает настоящую сквозную проверку вашего Drive: сервер запускается так же, как его запустил бы MCP-клиент, управляется через stdio официальным MCP-клиентом и проверяет поведение, которое заявляет этот проект — в том числе что устаревшая запись отклоняется, что отклонённая запись оставляет файл нетронутым, что ID файла не меняется после каждого редактирования и что нативный Google Doc переживает цикл «прочитать — отредактировать — прочитать» оставаясь Doc.

Он создаёт два временных файла в вашем Drive и перемещает их в корзину по завершении, в том числе при сбое на полпути. Ожидайте зелёную итоговую строку:

✓ ALL 41 CHECKS PASSED — the server works against live Drive.

Если что-то падает, вывод называет конкретную проверку и показывает, что вернулось. Проверки конфликта и нативного Doc несут дополнительную диагностику, объясняющую, что означает конкретный сбой — например, экранированный обратным слэшем # означает, что содержимое было импортировано как обычный текст, а не как markdown.

Это не формальность. Модульные тесты были зелёными на 49 тестах, и CI проходил, пока в коде сидел реальный дефект: создание нативного Doc из markdown молча давало Doc, содержащий буквальные символы # Heading. Поймал это только живой прогон, потому что мок кодировал то же неверное допущение, что и реализация. Запускайте это после любого изменения в drive.ts или mime.ts.

Справочник инструментов

read_file

Возвращает содержимое плюс revisionToken, mimeType и modifiedTime. Нативные файлы экспортируются (Docs → markdown, Sheets → CSV, Slides → обычный текст); бинарные файлы возвращаются в base64.

replace_in_file

Совпадение буквальное, не regex — . или $1 в вашем тексте поиска означают именно эти символы. Если oldString встречается более одного раза, а replaceAll равно false, вызов завершается ошибкой, а не угадывает, потому что тихая замена не того вхождения — это баг, которого никто не замечает.

append_to_file / prepend_to_file

Повторные добавления остаются равномерно разделёнными — без слипшихся строк и без растущих зазоров из пустых строк.

update_file_content

Заменяет всё. Без expectedRevisionToken перезапишет изменения, сделанные с момента вашего последнего чтения файла.

create_file

search_files

name contains 'budget'
fullText contains 'quarterly review'
'FOLDER_ID' in parents
mimeType = 'application/vnd.google-apps.document'

get_file_metadata / list_revisions

Оба принимают fileId; list_revisions также принимает необязательный pageSize.

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

Почему полный доступ к Drive. Этот сервер по умолчанию запрашивает https://www.googleapis.com/auth/drive. Более узкая область drive.file предоставляет доступ только к файлам, созданным самим приложением, что не подходит для инструмента, чья цель — редактировать уже существующие документы. Это реальный компромисс, о котором сказано прямо, а не спрятано: токен может читать и записывать всё в Drive авторизованного аккаунта.

Если ваш рабочий процесс касается только файлов, которые ассистент создаёт сам, запросите вместо этого более узкую область — и для шага авторизации, и для сервера:

GOOGLE_OAUTH_SCOPE=drive.file

Они должны совпадать. Refresh-токен несёт ту область, с которой был выдан, поэтому создание токена под одной областью и запуск сервера под другой приводит к запутывающим 403 при вызове. Сервер выводит предупреждение в stderr при запуске, когда активна область per-file, так что последующий 404 на чужом документе не будет загадкой.

Способы ограничить это:

• Авторизуйте выделенный аккаунт Google и предоставьте доступ только к конкретным файлам или папкам, которые должны быть доступны.

• Держите OAuth-приложение в режиме Testing, чтобы только перечисленные тестовые пользователи могли авторизоваться.

• Отзовите доступ в любой момент на myaccount.google.com/permissions.

Обращение с refresh-токеном. Это пароль к вашему Drive. Он никогда не истекает сам по себе. Храните его в .env (здесь он в git-ignore) или в конфиге вашего MCP-клиента, никогда не коммитьте его. Если он утёк, отзовите его по ссылке выше — это немедленно аннулирует его.

Никакой телеметрии. Этот сервер совершает сетевые вызовы только к API Google и никуда больше.

Устранение неполадок

Error 403: access_denied

Google отклоняет экран согласия до того, как выполняется этот код. auth/drive — ограниченная область, самый строгий уровень Google, и ограниченные области блокируются, если приложение не настроено на их разрешение. В Google Auth Platform проверьте в таком порядке:

1. Audience → статус публикации — "Testing", а не "In production". Непроверенное приложение в production не может использовать ограниченные области вообще, ни для кого, включая самого автора. Режим Testing разрешает их для до 100 перечисленных тестовых пользователей без проверки.

2. Audience → Test users включает точный аккаунт, с которым вы входите.

3. Branding — название приложения, email поддержки пользователей и контактный email разработчика сохранены. Неполный экран согласия — недействительный.

Изменения распространяются несколько минут. Если сразу после правки всё ещё не работает, подождите пять минут и повторите.

Чтобы полностью обойти это, запросите неограниченную область per-file, которая никогда не блокируется:

GOOGLE_OAUTH_SCOPE=drive.file npm run authorize

Каждый файл, к которому обращается npm run verify, создаётся им самим, поэтому полный набор проверок проходит под drive.file — это полезно для подтверждения работы сервера, пока конфигурация согласия ещё настраивается. Он не сможет получить доступ к документам, созданным в другом месте, так что это диагностический путь, а не постоянный.

Разработка

npm install
npm run build       # compile TypeScript to dist/
npm test            # build, then run the unit suite (no network, no credentials)
npm run verify      # end-to-end check against a real Drive account
npm run typecheck   # type-check without emitting
npm run watch       # rebuild on change

npm test и npm run verify отвечают на разные вопросы. Модульный набор тестов имитирует Drive API: он доказывает правильность логики, работает в CI и не требует учётных данных. npm run verify доказывает правильность интеграции — что Google действительно ведёт себя так, как предполагает этот сервер, особенно в отношении конвертации нативных файлов и токенов ревизий. Изменение в drive.ts или mime.ts следует проверять обоими способами.

Код организован так, что части, которые могут молча повредить документ, тестируются без обращения к сети:

src/
  index.ts    entry point; stdio transport
  auth.ts     OAuth client from environment
  drive.ts    Drive operations, incl. the concurrency guard
  edits.ts    pure text transforms — no I/O, fully unit-tested
  mime.ts     native vs. binary vs. textual classification
  tools.ts    MCP tool definitions and handlers
  errors.ts   error types written to be actionable by a model

Набор покрывает крайние случаи поиска/замены (литералы, похожие на regex, $& в заменах, многострочные цели, неоднозначные совпадения), логику швов append/prepend, классификацию MIME и защиту от параллельных запросов — включая то, что конфликтующая запись никогда не достигает API.

Вклад

Приветствуются issues и pull request'ы. Для изменения любого размера, пожалуйста, сначала откройте issue, чтобы согласовать подход до начала работы.

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

Лицензия

MIT — см. LICENSE.