Google Docs MCP

English | Русский

A1 Google Docs MCP позволяет AI-приложению читать и редактировать Google Docs на естественном языке. Можно прочитать документ как текст или Markdown, точечно изменить нужный фрагмент, оформить заголовки, списки и таблицы, разобрать ветки комментариев и выгрузить результат в PDF или DOCX.

Сервер работает с Google Docs API через ваш Google-аккаунт. Он правит текст по точным диапазонам индексов, а не наугад, и явно показывает ограничения Docs API, а не создаёт впечатление, что с документом можно сделать всё.

• 27 инструментов. Чтение документа как текста, структуры или Markdown, правка точных диапазонов, стили символов и абзацев, списки, таблицы, разрывы, изображения, ветки комментариев и экспорт в PDF, DOCX и другие форматы.
• Подключение из диалога. Скажите «подключи Google Документы»: сервер проведёт через создание OAuth-клиента, поймает редирект Google на 127.0.0.1 с PKCE и сам сохранит токены — без конфигов и перезапуска.
• Точечные правки. Изменения адресуются точными диапазонами индексов, и сервер подталкивает ассистента перечитывать документ перед каждой правкой, потому что каждое изменение сдвигает индексы после него.
• Markdown в обе стороны. Документ можно создать из Markdown или выгрузить в Markdown, PDF, DOCX и другие форматы; замена всего документа из Markdown — отдельный, явно разрушительный шаг.
• Без скрытого доступа к Drive. Экспорт, конвертация Markdown и комментарии внутри используют эндпоинты Drive, но отдельного инструмента общего назначения для Drive у сервера нет.

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

Прочитай документ с планом запуска и кратко перескажи открытые ветки комментариев.

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

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

Вы: Покажи текст и комментарии документа с планом запуска.

Ассистент: Читает документ как компактные текстовые блоки и перечисляет ветки комментариев. Ничего не меняется.

Вы: Перепиши абзац «Сроки»: бета начинается 3 марта.

Ассистент: Показывает точный диапазон, который заменит, и предлагаемый текст, затем запрашивает подтверждение перед правкой.

Вы: Подтверждаю.

Ассистент: Заменяет только этот диапазон. Остальной текст, форматирование и комментарии остаются как были.

Содержание

• Быстрый старт
• Что можно поручить
• Как меняется документ
• Что может измениться
• Как получить доступ
• Конфигурация
• Данные, лимиты и работа в фоне
• Техническая документация
• Поддержка

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

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

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

В приложении: откройте Settings → MCP servers, нажмите Add server, выберите STDIO, укажите команду npx -y @a1-x-tech/mcp-google-docs@latest и переменные окружения GOOGLE_DOCS_CLIENT_ID, GOOGLE_DOCS_CLIENT_SECRET, GOOGLE_DOCS_REFRESH_TOKEN, затем нажмите Save, потом Restart.

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

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

codex mcp list

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

claude mcp add \
  --transport stdio --scope user google-docs \
  -- npx -y @a1-x-tech/mcp-google-docs@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-docs": {
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-docs@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-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-docs@latest"]
    }
  }
}

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

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

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

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

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

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

Прочитать и выгрузить документ

• Прочитай этот документ как текст с заголовками и таблицами и перескажи его.
• Покажи дерево вкладок документа-справочника.
• Выгрузи спецификацию в Markdown; сохрани договор в PDF-файл.

Написать и отредактировать текст

• Создай документ с заметками встречи из этого Markdown.
• Вставь абзац с выводами после введения.
• Замени все «Q3» на «Q4» по всему документу.
• Удали устаревший раздел с ценами.

Оформить и структурировать

• Преврати эти абзацы в нумерованный список; сделай эту строку заголовком второго уровня.
• Выдели ключевые термины жирным и добавь на них ссылки на глоссарий.
• Вставь таблицу 3×4 для дорожной карты и заполни строку заголовков.
• Добавь разрыв страницы перед приложением; вставь изображение по публичному URL.

Работать с комментариями

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

Как меняется документ

1. create_document создаёт документ — пустой или сразу сконвертированный из Markdown.
2. Содержимое адресуется индексами — позициями UTF-16 внутри тела вкладки, — и каждая вставка или удаление сдвигает все последующие индексы. Сервер требует от ассистента брать свежие индексы из read_document_text перед каждой правкой и править с конца документа к началу.
3. import_markdown заменяет всё тело документа: якоря комментариев, позиционированные объекты, колонтитулы и дополнительные вкладки конвертацию не переживают.
4. Вкладки можно читать и адресовать, но API не умеет их создавать, переименовывать, удалять и переставлять.
5. Комментарии живут в Drive и управляются как ветки. Новый комментарий нельзя привязать к диапазону текста — формат якоря не опубликован, — поэтому он добавляется на уровне документа, при желании с цитатой текста, к которому относится.

Экспорт ограничен 10 МБ и не включает комментарии и предложенные правки. Встраиваемые изображения Google скачивает по публичному URL (PNG/JPEG/GIF, до 50 МБ и 25 мегапикселей); канала загрузки файлов изображений нет.

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

| Операция | Что происходит | Граница подтверждения | |---|---|---| | Чтение документа, вкладок и комментариев | Читает содержимое и структуру | Ничего не меняет | | Экспорт документа | Пишет локальный файл, если задан output_path; сам документ не меняется | Меняет только локальные файлы | | Создание документа | Добавляет новый документ | Меняет Google Docs | | Вставка текста, таблицы, разрыва или изображения | Добавляет содержимое | Меняет документ | | Стили текста и абзацев, управление списками | Перезаписывает форматирование диапазона | Меняет документ | | Замена или удаление диапазона, поиск с заменой | Удаляет существующее содержимое | Разрушительно | | Замена всего документа из Markdown | Заменяет всё тело документа | Разрушительно | | Управление комментариями | Создаёт, отвечает, закрывает или безвозвратно удаляет | Потенциально разрушительно | | Технический запрос API | Может вызвать метод API без отдельного инструмента | Потенциально разрушительно |

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

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

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

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

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

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

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

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

1. Создайте или выберите проект Google Cloud и включите оба API — Google Docs API и Google Drive API (экспорт, конвертация Markdown и комментарии идут через эндпоинты Drive).

2. Настройте OAuth consent screen и создайте OAuth-клиент типа Desktop app.

3. Авторизуйте Google-аккаунт, который владеет документами или может их редактировать. OAuth 2.0 Playground поможет получить refresh token, если включить Use your own OAuth credentials.

4. Запросите оба scope:

   https://www.googleapis.com/auth/documents
   https://www.googleapis.com/auth/drive

   Для более узкой настройки достаточно drive.file, если экспорт, Markdown и комментарии касаются только документов, созданных этим OAuth-клиентом, а пары documents.readonly + drive.readonly хватает для инструментов, которые только читают.

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

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

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

| Переменная | Обязательна | Описание | |---|---|---| | GOOGLE_DOCS_CLIENT_ID | Нет* | OAuth client ID. | | GOOGLE_DOCS_CLIENT_SECRET | Нет* | OAuth client secret. | | GOOGLE_DOCS_REFRESH_TOKEN | Нет* | OAuth refresh token. | | GOOGLE_DOCS_ACCESS_TOKEN | Нет* | Короткоживущая альтернатива OAuth-тройке (~1 час). | | GOOGLE_DOCS_OAUTH_PORT | Нет | Фиксированный порт loopback-слушателя для входа из диалога; нужен при пробросе портов по SSH. | | GOOGLE_DOCS_API_BASE | Нет | Переопределяет базовый URL Google Docs API. | | GOOGLE_DOCS_DRIVE_API_BASE | Нет | Переопределяет базовый URL Drive API (экспорт, Markdown, комментарии). | | GOOGLE_DOCS_TIMEOUT_MS | Нет | Тайм-аут одного запроса; по умолчанию 60000 мс. | | GOOGLE_DOCS_MAX_RETRIES | Нет | Повторы временных ошибок; по умолчанию 3. |

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

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

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

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

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

Поддержка

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