mcp-google-gmail

v0.2.0

Published

2 days ago

MCP server for the Gmail API — search, read and send email, manage drafts, labels and the trash. For Claude, Cursor, Codex and other AI clients.

0High
0Medium
0Low

gistrec

mcp model-context-protocol google gmail email mail drafts claude cursor codex

Gmail MCP

English | Русский

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

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

24 инструментов. Поиск и чтение писем и переписок, отправка напрямую или через черновики, полный жизненный цикл черновиков, ярлыки и корзина.
Подключение из диалога. Скажите «подключи Gmail»: сервер проведёт через создание OAuth-клиента, поймает редирект Google на 127.0.0.1 с PKCE и сам сохранит токены — без конфигов и перезапуска.
Осознанная отправка. Путь «черновик → проверка → отправка» — основной; отправка помечена как разрушительная, и после неоднозначного сбоя сервер никогда не отправляет письмо повторно — отправленное письмо не отозвать.
Корзина — страховка. Удаление почты идёт через обратимую корзину (около 30 дней); инструмента безвозвратного удаления писем сознательно нет.
Чтение с ограничителем. Декодированные тексты писем обрезаются по явному лимиту, а вложения возвращаются как метаданные, поэтому длинная рассылка не затопит диалог незаметно.
Минимальный scope Google. Используется только gmail.modify — без безвозвратного удаления и без доступа к настройкам Gmail.

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

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

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

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

Вы: Что непрочитанного пришло на этой неделе по контракту с Acme?
Ассистент: Ищет письма синтаксисом запросов Gmail и показывает отправителей, темы, даты и фрагменты. Ничего не меняется.
Вы: Подготовь ответ на последнее: подписанный экземпляр отправим в пятницу.
Ассистент: Создаёт черновик в той же переписке и показывает его на проверку. Ничего не отправлено.
Вы: Отправляй.
Ассистент: Отправляет черновик. Отправка — отдельный, явно разрушительный шаг, поэтому AI-приложение может сначала запросить подтверждение.

Содержание

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

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

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

В приложении: откройте Settings → MCP servers, нажмите Add server, выберите STDIO, укажите команду npx -y mcp-google-gmail@latest и переменные окружения GOOGLE_GMAIL_CLIENT_ID, GOOGLE_GMAIL_CLIENT_SECRET, GOOGLE_GMAIL_REFRESH_TOKEN, затем нажмите Save, потом Restart.

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

codex mcp add google-gmail \
  -- npx -y mcp-google-gmail@latest

codex mcp list

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

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

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

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

{
  "servers": {
    "google-gmail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-gmail@latest"]
    }
  }
}

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

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

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

Разобрать входящие

Покажи непрочитанные письма за последние семь дней и сгруппируй по отправителям.
Найди переписку с Acme о контракте и суммируй её от старых писем к новым.
В каких письмах меня ждут вложения? Покажи темы и имена файлов.

Написать и отправить письмо

Подготовь ответ в этой переписке: подписанный экземпляр уйдёт в пятницу.
Покажи черновик, сделай формулировки короче, затем отправь.
Отправь команде короткое письмо о статусе, руководителя поставь в копию.

Поддерживать порядок в почте

Создай ярлык Receipts/2026 и присвой его подходящим письмам.
Отметь рассылки этой недели прочитанными и заархивируй их.
Перемести эту переписку в корзину — и восстанови, если я передумаю.

Как меняется почта

Безопасный путь к отправке — черновик: create_draft готовит письмо, get_draft показывает его на проверку, send_draft отправляет. send_message пропускает черновик и отправляет сразу.
Отправленное письмо необратимо во внешнем мире. После тайм-аута или ошибки 5xx сервер не отправляет повторно; прежде чем пробовать снова, проверьте письма по запросу in:sent — повторённая отправка означала бы письмо, ушедшее дважды.
Удалить письмо или переписку — значит отправить в корзину. manage_trash обратим около 30 дней; инструмента безвозвратного удаления сознательно нет.
Черновики — исключение: update_draft заменяет черновик целиком (частичного редактирования в API нет), а delete_draft необратим, потому что черновики минуют корзину.

Каждый вызов работает с одним почтовым ящиком — аккаунтом, выдавшим токен. Декодированные тексты обрезаются по настраиваемому лимиту с явными флагами, а вложения возвращаются только как метаданные; содержимое вложений запрашивается через raw_request осознанно.

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

| Операция | Что происходит | Граница подтверждения | |---|---|---| | Поиск и чтение писем, переписок, черновиков, ярлыков, профиля | Читает данные почтового ящика | Ничего не меняет | | Создание или обновление черновика | Готовит или заменяет неотправленное письмо | Меняет почтовый ящик | | Смена состояния «прочитано», «в избранном», «в архиве», присвоение или снятие ярлыков | Меняет организацию почты | Меняет почтовый ящик | | Создание или переименование ярлыка | Меняет словарь ярлыков | Меняет почтовый ящик | | Корзина: отправка или восстановление письма или переписки | Перемещает почту в корзину и обратно; обратимо ~30 дней | Разрушительно | | Отправка письма или черновика | Доставляет письмо реальным получателям; его не отозвать | Разрушительно | | Удаление черновика или ярлыка | Удаляет его безвозвратно, минуя корзину | Разрушительно | | Технический запрос API | Может вызвать метод API без отдельного инструмента | Потенциально разрушительно |

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

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

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

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

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

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

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

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

Создайте или выберите проект Google Cloud и включите Gmail API.
Настройте OAuth consent screen и создайте OAuth-клиент типа Desktop app.
Авторизуйте Google-аккаунт, чей почтовый ящик хотите подключить, — каждый вызов работает именно с этим ящиком. OAuth 2.0 Playground поможет получить refresh token, если включить Use your own OAuth credentials.
Запросите scope:
```
https://www.googleapis.com/auth/gmail.modify
```
Он покрывает поиск, чтение, отправку, черновики, ярлыки и корзину — но не безвозвратное удаление и не настройки Gmail. Для безвозвратного удаления через raw_request дополнительно нужен полный scope https://mail.google.com/.

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

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

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

| Переменная | Обязательна | Описание | |---|---|---| | GOOGLE_GMAIL_CLIENT_ID | Нет* | OAuth client ID. | | GOOGLE_GMAIL_CLIENT_SECRET | Нет* | OAuth client secret. | | GOOGLE_GMAIL_REFRESH_TOKEN | Нет* | OAuth refresh token. | | GOOGLE_GMAIL_ACCESS_TOKEN | Нет* | Короткоживущая альтернатива OAuth-тройке (около 1 часа). | | GOOGLE_GMAIL_OAUTH_PORT | Нет | Фиксированный порт loopback-слушателя для входа из диалога; нужен при пробросе портов по SSH. | | GOOGLE_GMAIL_API_BASE | Нет | Переопределяет базовый URL Gmail API. | | GOOGLE_GMAIL_TIMEOUT_MS | Нет | Тайм-аут одного запроса; по умолчанию 60000 мс. | | GOOGLE_GMAIL_MAX_RETRIES | Нет | Повторы временных ошибок; по умолчанию 3. |

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

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

Запросы идут в Gmail. Локальный сервер обновляет OAuth-токены Google и вызывает Gmail API. Анонимная телеметрия содержит ID установки, версию пакета, версии AI-клиента и платформы и имена инструментов — но не OAuth-токены, содержимое почты, аргументы или промпты. Чтобы отключить её, задайте ASKADS_TELEMETRY=0.
Google считает единицы квоты. Gmail разрешает примерно 250 единиц квоты в секунду на пользователя; отправка стоит 100 единиц, обычное чтение — 5. Обычные аккаунты отправляют около 500 писем в день, аккаунты Workspace — около 2000. При 429 сервер использует задержку; чтение также повторяется после сетевых и 5xx ошибок, а отправка и другие записи после неопределённой ошибки не повторяются никогда.
Постоянного опроса нет. Сервер работает только при вызове. Если AI-приложение поддерживает задания по расписанию, оно может периодически проверять входящие; через raw_request также доступен history.list для инкрементальной синхронизации.

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

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

Поддержка

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