google-workspace-mcp

Многопользовательский, токен-эффективный MCP для Gmail + Calendar + Drive + Docs + Sheets. Создан, потому что официальный коннектор Claude поддерживает только одну учетную запись и по умолчанию возвращает полные тела сообщений/файлов.

Почему это существует

• Многопользовательский режим: OAuth для нескольких почтовых ящиков (рабочий + личный + сооснователь). Каждый инструмент принимает email account; псевдонимы обрабатываются через идентификаторы Send-As.

• Токен-эффективность: Поиск/список возвращает компактные формы ({id, from, subject, snippet, ...} для почты, {id, name, mime, modified, size, ...} для Drive). Тела писем и содержимое файлов доступны по запросу.

• На базе связки ключей (Keychain): Токены обновления хранятся в macOS Keychain, а не в текстовых файлах. Никаких токенов в хранилище, никаких токенов в репозиториях.

Инструменты (v2, 61 инструмент)

Управление учетными записями (3)

• gws_account_add — процесс OAuth в браузере, добавление нового авторизованного почтового ящика

• gws_account_list — список авторизованных учетных записей + учетная запись по умолчанию

• gws_account_remove — удаление локальных учетных данных (не отзывает доступ на стороне Google)

Gmail (10)

• gmail_search — поиск с использованием операторов Gmail. Компактный ответ.

• gmail_read — чтение одного сообщения или всей цепочки. Тела писем по запросу.

• gmail_send — отправка почты, опциональный from_alias для идентификаторов Send-As

• gmail_draft — создание черновика

• gmail_reply — ответ (сохраняет цепочку + заголовки), опционально reply_all

• gmail_labels_list — список всех ярлыков

• gmail_label_apply — пакетное добавление/удаление ярлыков

• gmail_archive — пакетное архивирование (удаление из INBOX)

• gmail_trash — пакетное перемещение в корзину

• gmail_sendas_list — список идентификаторов Send-As для этого почтового ящика

Календарь (7)

• cal_list_calendars — список всех календарей

• cal_list_events — список предстоящих событий (по умолчанию компактно, verbose=True для полной информации)

• cal_create_event — создание события, опциональная ссылка на Google Meet

• cal_update_event — частичное обновление полей

• cal_delete_event — удаление

• cal_freebusy — проверка занятости для планирования

• cal_respond — принять/отклонить/возможно

Диск (18)

• drive_search — свободный текст или raw q-синтаксис Drive. Ответ только с метаданными.

• drive_read_file — по умолчанию метаданные; include_content=True для тела файла

• drive_list_folder — прямые дочерние элементы папки ('root' для Моего диска)

• drive_create_folder — создание папки в опциональной родительской папке

• drive_upload — загрузка локального файла, опционально convert_to_google

• drive_move — изменение родительской папки

• drive_rename — переименование файла или папки

• drive_share — предоставление доступа (читатель/комментатор/редактор и т.д.) по email

• drive_trash — мягкое удаление (можно восстановить)

• drive_untrash — восстановление из корзины

• drive_permission_list — список всех, у кого есть доступ к файлу

• drive_permission_update — изменение роли пользователя

• drive_permission_delete — отзыв разрешения

• drive_shared_drives_list — список общих дисков, к которым имеет доступ эта учетная запись

• drive_comments_list — список комментариев к любому файлу на Диске (Doc/Sheet/Slide/загруженный файл)

• drive_comment_add — добавление комментария, опциональный якорь

• drive_comment_reply — ответ на комментарий

• drive_comment_resolve — отметить комментарий как решенный

Документы (9)

• docs_create — новый документ, опционально начальное тело и родительская папка

• docs_read — по умолчанию плоский текст; structured=True для полного дерева Docs API

• docs_append — добавление текста в конец документа

• docs_insert_at — вставка текста по определенному индексу

• docs_replace_text — поиск и замена, возвращает количество замен

• docs_export — экспорт в markdown / pdf / docx / rtf / plain

• docs_suggestions_list — список ожидающих предложений по отслеживаемым изменениям

• docs_suggestions_accept_all — принять все предложения (перезаписывает документ)

• docs_suggestions_reject_all — отклонить все предложения (перезаписывает документ)

Таблицы (14)

• sheets_create — новая книга, опциональная родительская папка

• sheets_list_sheets — список вкладок с размерами строк/столбцов

• sheets_add_sheet — добавление новой вкладки в существующую книгу

• sheets_read_range — чтение диапазона A1. Опции FORMULA / UNFORMATTED_VALUE.

• sheets_write_range — перезапись диапазона. USER_ENTERED парсит формулы.

• sheets_append — добавление строк после существующих данных

• sheets_clear_range — очистка значений (форматирование сохраняется)

• sheets_batch_read — чтение нескольких диапазонов за один вызов API

• sheets_batch_write — запись в несколько диапазонов за один вызов API

• sheets_named_ranges_list — список именованных диапазонов в книге

• sheets_named_range_add — создание именованного диапазона

• sheets_named_range_delete — удаление именованного диапазона

• sheets_conditional_format_add — добавление правила условного форматирования

• sheets_data_validation_add — установка проверки данных (выпадающий список / число / email / URL)

Установка

См. SETUP.md для однократной настройки GCP (~45 минут для v1, ~5 минут дополнительно для включения Drive/Docs/Sheets для v2).

После настройки:

pip3 install --break-system-packages -r requirements.txt

Регистрация в Claude Code

Добавьте в .mcp.json вашего проекта (или ~/.claude.json для глобального доступа):

"google-workspace": {
  "type": "stdio",
  "command": "python3",
  "args": ["/path/to/google-workspace-mcp/server.py"]
}

Обновление с v1 → v2

v2 добавляет области (scopes) Drive + Docs + Sheets. Каждая авторизованная учетная запись должна пройти OAuth повторно, чтобы Google предоставил новые области. См. шаг 6b в SETUP.md.

Дорожная карта

• v3: Фильтры Gmail, автоответчик, push-уведомления (Gmail Watch), ACL/делегирование календаря, Slides, Forms, Tasks

• v4: Пакетные запросы между сервисами, версии Drive

Лицензия

MIT