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). Тела и содержимое файлов — по запросу.

• Хранение в Keyring: Refresh-токены хранятся в хранилище учётных данных ОС — Keychain на macOS, Credential Manager на Windows, Secret Service на Linux — а не в открытых текстовых файлах. Никаких токенов в vault, никаких токенов в репозиториях.

• macOS, Windows и Linux: один установщик на платформу, один и тот же коннектор.

Related MCP server: google-workspace-mcp

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

Управление аккаунтами (3)

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

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

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

Gmail (12)

• 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 на этом почтовом ящике

• gmail_attachments_list — список вложений сообщения (имя файла, MIME-тип, размер)

• gmail_attachment_save — загрузка одного вложения в локальный файл, возвращается путь для прямого чтения

Calendar (7)

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

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

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

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

• cal_delete_event — удаление

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

• cal_respond — принять/отклонить/предварительно принять

Drive (18)

• drive_search — свободный текст или сырой 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 — список комментариев к любому файлу Drive (Doc/Sheet/Slide/загруженный)

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

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

• drive_comment_resolve — пометка комментария как решённого

Docs (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 — отклонить все предложения (перезаписывает документ)

Sheets (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

Установка

Самый быстрый путь — один скрипт, без ручной настройки.

macOS и Linux:

git clone https://github.com/adelaidasofia/google-workspace-mcp.git
bash google-workspace-mcp/install.sh

Windows (PowerShell):

git clone https://github.com/adelaidasofia/google-workspace-mcp.git
powershell -ExecutionPolicy Bypass -File .\google-workspace-mcp\install.ps1

Установщик создаёт изолированное venv, устанавливает зависимости, принимает ваш Google OAuth-клиент (интерактивно или через GWS_CLIENT_ID / GWS_CLIENT_SECRET в переменных окружения) и регистрирует сервер в Claude Code. Повторный запуск безопасен. Вам всё равно сначала понадобится Google OAuth-клиент — см. SETUP.md для разовой настройки GCP (~45 минут). Затем запустите gws_account_add из Claude Code, чтобы авторизовать первый почтовый ящик.

Для обоих нужен Python 3.10 или новее; установщик найдёт уже установленную версию.

• macOS / Linux сначала пробует python3, затем python3.14 и ниже до python3.10, так что Homebrew Python тоже подойдёт, когда python3 указывает на старую системную версию macOS.

• Windows сначала пробует py -3 (лаунчер Python), затем python, python3 и версионированные имена. Каждый кандидат должен запуститься и сообщить свою версию, прежде чем будет принят — именно это не даёт заглушке Microsoft Store в %LOCALAPPDATA%\Microsoft\WindowsApps быть выбранной: это настоящий python.exe в PATH, который лишь открывает Store.

Если ваш Python находится там, где поиск не найдёт (pyenv, conda, приватный префикс), укажите его явно:

GWS_PYTHON=/full/path/to/python3 bash google-workspace-mcp/install.sh

$env:GWS_PYTHON = 'C:\full\path\to\python.exe'
powershell -ExecutionPolicy Bypass -File .\google-workspace-mcp\install.ps1

-ExecutionPolicy Bypass в команде — намеренно. Windows по умолчанию блокирует загруженные скрипты; это применяет исключение к одному запуску, не меняя политику машины.

Запускайте из PowerShell, а не из Git Bash. install.sh обнаруживает Git Bash / MSYS и останавливается с указанием на install.ps1, вместо того чтобы регистрировать POSIX-путь venv, который нативный Claude Code не сможет запустить. WSL — это настоящий Linux, там по-прежнему используется install.sh.

Часовой пояс. Коннектор читает IANA-зону машины, чтобы «15:00» в вызове cal_* означало 15:00 там, где вы находитесь. Windows называет свои зоны по-своему (SA Western Standard Time), поэтому используется tzlocal, который установщик подтягивает. Задайте GWS_TIME_ZONE=America/Bogota для переопределения.

Откройте Claude Code и вставьте:

/plugin marketplace add adelaidasofia/google-workspace-mcp
/plugin install google-workspace-mcp@google-workspace-mcp

Вам всё равно нужно завершить разовую настройку GCP из SETUP.md (~45 минут для v1, ~5 минут дополнительно для v2 Drive/Docs/Sheets), чтобы у сервера был client_secret.json для OAuth. Запустите gws_account_add из Claude Code, чтобы авторизовать первый почтовый ящик.

На Windows после этого запустите install.ps1. .mcp.json плагина запускает сервер через python3, а манифест плагина не имеет способа сказать «кроме Windows, используй это». На Windows python3 либо отсутствует, либо является заглушкой Microsoft Store, поэтому коннектор регистрируется, но никогда не запускается. install.ps1 перерегистрирует его с абсолютным путём к интерпретатору, что однозначно на любой платформе.

См. 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"]
}

На Windows укажите полный путь к настоящему интерпретатору, а не голое имя — python3 там обычно является заглушкой Microsoft Store, которая корректно резолвится, но никогда не запускает Python:

"google-workspace": {
  "type": "stdio",
  "command": "C:\\Users\\you\\google-workspace-mcp\\.venv\\Scripts\\python.exe",
  "args": ["C:\\Users\\you\\google-workspace-mcp\\server.py"]
}

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

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

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

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

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

Связанные MCP

Тот же автор, тот же архитектурный паттерн (FastMCP, черновик+подтверждение для записей где применимо, автоэкспорт в vault, MIT):

• slack-mcp — мультиворкспейсный Slack

• imessage-mcp — iMessage на macOS

• whatsapp-mcp — WhatsApp через whatsmeow

• apollo-mcp — Apollo.io CRM + последовательности

• substack-mcp — написание в Substack + аналитика

• luma-mcp — события lu.ma

• parse-mcp — маршрутизатор markitdown / Docling / LlamaParse

• rescuetime-mcp — данные продуктивности RescueTime

• graph-query-mcp — запросы к графу знаний vault

• graph-autotagger-mcp — предложения вики-ссылок из графа

• investor-relations-mcp — трекер пайплайна посевного раунда

• vault-sync-mcp — двунаправленная синхронизация vault

Телеметрия

Этот плагин отправляет единственный анонимный сигнал об установке на myceliumai.co при первой загрузке в сессии Claude Code на данной машине.

Что отправляется:

• Имя плагина (например, slack-mcp)

• Версия плагина (например, 0.1.0)

Что НЕ отправляется:

• Никаких идентификаторов пользователей, имён, email, токенов или API-ключей

• Никаких путей к файлам, содержимого сообщений или чего-либо из вашей работы

• IP-адрес не хранится после обработки дедупликации

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

Отказ: Установите переменную окружения MYCELIUM_NO_PING=1 перед запуском Claude Code. Хук полностью пропустит сетевой вызов. Уже опрошенные установки оставляют маркер в ~/.mycelium/onboarded-<plugin> — удалите его, если хотите сбросить состояние.

Лицензия

MIT

Создано Mycelium AI. Полная установка или командная версия на diazroa.com.