gdocs — цикл рецензирования Google Docs для Claude Code

MCP-сервер, который позволяет Claude Code читать Google Doc и его ветки комментариев, а затем записывать исправления обратно в тот же документ по тому же URL.

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

Устанавливается на уровне пользователя, поэтому работает во всех проектах.

Требования

• Node 18+

• CLI claude

• Учётная запись Google и около 10 минут в Google Cloud Console

Установка

git clone https://github.com/uma-victor1/gdocs-mcp.git
cd gdocs-mcp
./install.sh

Это устанавливает зависимости, проверяет запуск сервера и регистрирует его в Claude Code на уровне пользователя. Два шага с учётными данными ниже выполните самостоятельно.

1. Google Cloud, один раз

1. Создайте проект: https://console.cloud.google.com/projectcreate

2. Включите Google Docs API и Google Drive API (APIs & Services > Library)

3. Экран согласия OAuth: тип пользователя External подойдёт для личного аккаунта. В разделе Audience добавьте свой адрес как тестового пользователя — пропуск этого шага является самой частой причиной сбоя согласия.

4. Credentials > Create credentials > OAuth client ID > Desktop app > Скачайте JSON

5. Сохраните его как ~/.config/gdocs-mcp/credentials.json

Учётные данные намеренно хранятся вне любого репозитория, поэтому git add -A никогда не сможет их закоммитить.

2. Авторизуйтесь, один раз

npm run auth

Google предупреждает, что приложение не прошло проверку. Это ожидаемо для приложения с одним пользователем: Advanced > Go to ... (unsafe). Refresh-токен сохраняется в ~/.config/gdocs-mcp/token.json с правами 0600.

Перезапустите Claude Code, затем проверьте с помощью claude mcp list.

Семидневная повторная авторизация и почему

Пока экран согласия находится в Testing, Google аннулирует refresh-токен каждые 7 дней. Это задокументированное поведение для внешних приложений на стадии тестирования, а не баг, и обойти его для такого набора областей доступа нельзя: auth/drive — restricted scope, а публикация в production с restricted scope требует оценки безопасности CASA — для инструмента для одного человека это того не стоит.

Поэтому примерно раз в неделю вызов инструмента будет падать с ошибкой «Authorisation expired». Исправление:

npm run auth

Пятнадцать секунд. Если у вас есть аккаунт Google Workspace, вы можете полностью избежать этого: создайте Cloud-проект в этой организации и установите для экрана согласия тип пользователя Internal. Внутренние приложения не имеют срока действия в 7 дней и списка тестовых пользователей.

Инструменты

Все инструменты принимают URL документа или просто fileId.

Компромисс с якорями комментариев

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

• Мелкие правки → replace_text. Якоря сохраняются; рецензенты сохраняют контекст.

• Структурные переписывания → push_markdown. Быстрее, но ожидаем потеря комментариев. Инструмент сообщает, сколько открытых веток было до, поэтому ущерб заметен, а не молчалив.

• Добавление вместо изменения → append_text. Он вставляет только в конец, поэтому существующий фрагмент не сдвигается и якорь не ломается.

• Сначала ответьте, потом переписывайте. reply_comment оставляет запись о том, что изменилось и зачем.

Почему этот сервер, а не готовый

MCP-сервер с OAuth-токеном для Docs может читать и переписывать все документы в аккаунте. Не существует официального MCP-сервера для Docs от Google или Anthropic; все опубликованные — это сторонние пакеты от отдельных издателей. Этот написан на ~250 строках MCP SDK от Anthropic и собственного клиентской библиотеки Google — достаточно мал, чтобы его можно было прочитать, прежде чем доверять ему.

Режим только для чтения

claude mcp remove gdocs -s user
claude mcp add gdocs -s user -e GDOCS_MCP_READONLY=1 -- node "$PWD/server.mjs"

Чтение продолжает работать; все инструменты записи отказываются. Это полезно, когда документом владеет кто-то другой.

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

Проверить сервер независимо можно в любое время с помощью npm run smoke.

Чтобы опробовать отдельный инструмент без участия Claude Code:

node call.mjs read_comments '{"doc":"https://docs.google.com/document/d/FILEID/edit"}'

Отзыв доступа

https://myaccount.google.com/permissions, затем удалите ~/.config/gdocs-mcp/token.json.

Структура

server.mjs         the nine tools
google.mjs         auth + Drive/Docs clients; credential paths
auth.mjs           one-time interactive OAuth   (npm run auth)
smoke.mjs          starts the server, lists tools  (npm run smoke)
call.mjs           invoke one tool from the shell, for debugging
install.sh         deps, verify, register at user scope
docs/guide.html    the setup walkthrough as a standalone page

Лицензия

MIT. См. LICENSE.