Google Sheets MCP

English | Русский

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

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

• 26 инструментов. Поиск и создание таблиц, чтение и запись диапазонов, управление листами, форматированием, проверкой данных, защищёнными диапазонами, условным форматированием, структурированными таблицами, диаграммами и доступом.
• Подключение из диалога. Скажите «подключи Google Таблицы»: сервер проведёт через создание OAuth-клиента, поймает редирект Google на 127.0.0.1 с PKCE и сам сохранит токены — без конфигов и перезапуска.
• Осознанная запись. Запись никогда не повторяется после неопределённой ошибки — повтор append продублировал бы строки, — а разрушительные инструменты помечены, чтобы AI-клиент мог сначала спросить.
• Только Sheets. Drive — внутренняя зависимость лишь для поиска таблиц и управления доступом; отдельного Drive-инструмента нет, и raw_request до Drive не дотягивается.
• Минимальные scope Google. spreadsheets покрывает каждый Sheets-инструмент; scope Drive нужен только для поиска таблиц и управления доступом.

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

Найди таблицу с квартальным бюджетом и кратко расскажи, что на каждом её листе.

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

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

Вы: Покажи структуру таблицы с отчётом о продажах: листы, их размеры и закреплённые строки.

Ассистент: Показывает листы, их размеры, закреплённые заголовки и объекты на них. Ничего не меняется.

Вы: Подготовь лист «Март» как копию «Февраля» и очисти цифры, сохранив оформление.

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

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

Ассистент: Дублирует лист и очищает значения. Форматирование, проверка данных и закреплённые строки остаются.

Содержание

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

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

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

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

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

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

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

codex mcp list

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

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

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

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

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

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

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

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

Найти и прочитать данные

• Найди самую свежую таблицу со словом «бюджет» в названии и покажи её структуру.
• Прочитай 'Q3'!A1:F50 и суммируй итоги.
• Покажи формулы, по которым считается лист «Итоги».

Обновить цифры

• Запиши эту таблицу в Sheet1!A1 вместе с формулами.
• Добавь сегодняшние показатели новой строкой журнала.
• Обнови несколько диапазонов одним пакетом или очисти черновой диапазон, сохранив его оформление.

Оформить и показать

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

Защитить и поделиться

• Защити строку итогов, чтобы её мог менять только я.
• Дай коллеге право редактирования, а остальным — только чтение.
• Покажи, у кого сейчас есть доступ к файлу.

Как меняется таблица

1. Инструменты значений адресуют ячейки в нотации A1 ('Имя листа'!A1:C10); структурные инструменты (листы, форматирование, правила, таблицы, диаграммы) адресуют числовой sheetId и индексы с отсчётом от нуля. Идентификаторы даёт get_spreadsheet — названия листов адресами не являются.
2. Запись перезаписывает свой диапазон; append_values добавляет строки после последней строки данных; ячейка null пропускается, а не очищается.
3. clear_values очищает значения и формулы, но сохраняет форматирование, проверку данных, заметки и объединения. Отмены через API нет — удаление листа, строк или столбцов уничтожает их данные.
4. Пакетные инструменты переносят несколько диапазонов или запросов одним вызовом и считаются в квоте один раз; batchUpdate атомарен — применяются все его запросы или ни один.

У части возможностей таблиц нет отдельного инструмента: объединённые ячейки, именованные диапазоны, чередование цветов, фильтры, срезы, поиск с заменой и градиентные правила условного форматирования доступны через raw_request, который ограничен доменом Sheets API. Новая таблица создаётся в корне My Drive — перенос в папку сервер не покрывает, а manage_permissions не передаёт владение файлом.

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

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

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

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

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

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

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

1. setup_instructions выдаёт чек-лист: создать или выбрать проект Google Cloud, включить Google Sheets 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-sheets/credentials.json (права 0600).

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

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

1. Создайте или выберите проект Google Cloud и включите Google Sheets API. Включите также Google Drive API, если нужны поиск таблиц и управление доступом.

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/spreadsheets

   Он покрывает каждый Sheets-инструмент. Дополнительный scope Drive нужен только search_spreadsheets и manage_permissions: https://www.googleapis.com/auth/drive, либо drive.readonly только для поиска, либо drive.file для файлов, созданных через это приложение.

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

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

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

| Переменная | Обязательна | Описание | |---|---|---| | GOOGLE_SHEETS_CLIENT_ID | Нет* | OAuth client ID. | | GOOGLE_SHEETS_CLIENT_SECRET | Нет* | OAuth client secret. | | GOOGLE_SHEETS_REFRESH_TOKEN | Нет* | OAuth refresh token. | | GOOGLE_SHEETS_ACCESS_TOKEN | Нет* | Короткоживущая (~1 ч) альтернатива OAuth-тройке. | | GOOGLE_SHEETS_OAUTH_PORT | Нет | Фиксированный порт loopback-слушателя для входа из диалога; нужен при пробросе портов по SSH. | | GOOGLE_SHEETS_API_BASE | Нет | Переопределяет базовый URL Google Sheets API. | | GOOGLE_SHEETS_TIMEOUT_MS | Нет | Тайм-аут одного запроса; по умолчанию 60000 мс. | | GOOGLE_SHEETS_MAX_RETRIES | Нет | Повторы временных ошибок; по умолчанию 3. |

* Передайте OAuth-тройку или access token. Без учётных данных сервер всё равно запустится и покажет инструменты; первый вызов назовёт переменные, которые нужно задать.

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

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

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

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

Поддержка

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