Gmail AutoAuth MCP-сервер

Сервер Model Context Protocol (MCP) для интеграции Gmail в Claude Desktop с поддержкой автоматической аутентификации. Этот сервер позволяет помощникам ИИ управлять Gmail посредством взаимодействия на естественном языке.

Функции

Отправка электронных писем с темой, содержанием, вложениями и получателями
Поддержка HTML-писем и многокомпонентных сообщений с версиями HTML и обычного текста
Полная поддержка международных символов в темах и содержимом писем
Чтение сообщений электронной почты по идентификатору с расширенной обработкой структуры MIME
Просмотр информации о вложениях электронной почты (имена файлов, типы, размеры)
Поиск писем по различным критериям (тема, отправитель, диапазон дат)
Комплексное управление этикетками с возможностью создания, обновления, удаления и составления списка этикеток
Список всех доступных ярлыков Gmail (системных и пользовательских)
Список писем в папке «Входящие», «Отправленные» или с пользовательскими метками
Отметить письма как прочитанные/непрочитанные
Перемещать электронные письма в разные метки/папки
Удалить электронные письма
Пакетные операции для эффективной обработки нескольких писем одновременно
Полная интеграция с API Gmail
Простой процесс аутентификации OAuth2 с автоматическим запуском браузера
Поддержка учетных данных как настольных, так и веб-приложений
Глобальное хранилище учетных данных для удобства

Установка и аутентификация

Установка через Smithery

Чтобы автоматически установить Gmail AutoAuth для Claude Desktop через Smithery :

npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude

Установка вручную

Создайте проект Google Cloud и получите учетные данные:а. Создайте проект Google Cloud:
- Перейти в Google Cloud Console
- Создайте новый проект или выберите существующий
- Включите API Gmail для вашего проекта
б) Создайте учетные данные OAuth 2.0:
- Перейдите в раздел «API и службы» > «Учетные данные».
- Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth».
- Выберите тип приложения: «Приложение для настольного компьютера» или «Веб-приложение».
- Дайте ему имя и нажмите «Создать».
- Для веб-приложения добавьте http://localhost:3000/oauth2callback к разрешенным URI перенаправления.
- Загрузите JSON-файл ключей OAuth вашего клиента
- Переименуйте файл ключа в gcp-oauth.keys.json
Запустить аутентификацию:Аутентификацию можно пройти двумя способами:а. Глобальная аутентификация (рекомендуется):
# First time: Place gcp-oauth.keys.json in your home directory's .gmail-mcp folder mkdir -p ~/.gmail-mcp mv gcp-oauth.keys.json ~/.gmail-mcp/ # Run authentication from anywhere npx @gongrzhe/server-gmail-autoauth-mcp auth
б) Локальная аутентификация:
# Place gcp-oauth.keys.json in your current directory # The file will be automatically copied to global config npx @gongrzhe/server-gmail-autoauth-mcp auth
Процесс аутентификации будет:
- Найдите gcp-oauth.keys.json в текущем каталоге или ~/.gmail-mcp/
- Если файл найден в текущем каталоге, скопируйте его в ~/.gmail-mcp/
- Откройте браузер по умолчанию для аутентификации Google
- Сохраните учетные данные как ~/.gmail-mcp/credentials.json
Примечание :
- После успешной аутентификации учетные данные сохраняются глобально в ~/.gmail-mcp/ и могут быть использованы из любого каталога.
- Поддерживаются учетные данные как настольного приложения, так и веб-приложения.
- Для учетных данных веб-приложения обязательно добавьте http://localhost:3000/oauth2callback к вашим авторизованным URI перенаправления.
Настройте в Claude Desktop:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@gongrzhe/server-gmail-autoauth-mcp"
      ]
    }
  }
}

Поддержка докера

Если вы предпочитаете использовать Docker:

Аутентификация:

docker run -i --rm \
  --mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
  -v mcp-gmail:/gmail-server \
  -e GMAIL_OAUTH_PATH=/gcp-oauth.keys.json \
  -e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \
  -p 3000:3000 \
  mcp/gmail auth

Использование:

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "mcp-gmail:/gmail-server",
        "-e",
        "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json",
        "mcp/gmail"
      ]
    }
  }
}

Аутентификация облачного сервера

Для облачных серверных сред (например, n8n) вы можете указать пользовательский URL-адрес обратного вызова во время аутентификации:

npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback

Инструкции по настройке облачной среды

Настроить обратный прокси-сервер:
- Настройте контейнер n8n для предоставления порта для аутентификации
- Настройте обратный прокси-сервер для пересылки трафика с вашего домена (например, gmail.gongrzhe.com ) на этот порт
Конфигурация DNS:
- Добавьте запись A в настройки DNS, чтобы преобразовать ваш домен в IP-адрес вашего облачного сервера.
Настройка облачной платформы Google:
- В консоли Google Cloud Console добавьте URL-адрес обратного вызова вашего домена (например, https://gmail.gongrzhe.com/oauth2callback ) в список разрешенных URI перенаправления.
Запустить аутентификацию:
npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback
Настройте в своем приложении:
{ "mcpServers": { "gmail": { "command": "npx", "args": [ "@gongrzhe/server-gmail-autoauth-mcp" ] } } }

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

Доступные инструменты

Сервер предоставляет следующие инструменты, которые можно использовать через Claude Desktop:

1. Отправить электронное письмо ( `send_email` )

Немедленно отправляет новое письмо. Поддерживает простой текст, HTML или многокомпонентные письма.

{
  "to": ["recipient@example.com"],
  "subject": "Meeting Tomorrow",
  "body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"],
  "mimeType": "text/plain"
}

Пример HTML-письма:

{
  "to": ["recipient@example.com"],
  "subject": "Meeting Tomorrow",
  "mimeType": "text/html",
  "body": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}

Пример составного электронного письма (HTML + обычный текст):

{
  "to": ["recipient@example.com"],
  "subject": "Meeting Tomorrow",
  "mimeType": "multipart/alternative",
  "body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
  "htmlBody": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}

2. Черновик электронного письма ( `draft_email` )

Создает черновик электронного письма, не отправляя его.

{
  "to": ["recipient@example.com"],
  "subject": "Draft Report",
  "body": "Here's the draft report for your review.",
  "cc": ["manager@example.com"]
}

3. Прочитать письмо ( `read_email` )

Извлекает содержимое определенного электронного письма по его идентификатору.

{
  "messageId": "182ab45cd67ef"
}

4. Поиск писем ( `search_emails` )

Поиск писем с использованием синтаксиса поиска Gmail.

{
  "query": "from:sender@example.com after:2024/01/01 has:attachment",
  "maxResults": 10
}

5. Изменить адрес электронной почты ( `modify_email` )

Добавляет или удаляет метки из писем (перемещать в другие папки, архивировать и т. д.).

{
  "messageId": "182ab45cd67ef",
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"]
}

6. Удалить электронное письмо ( `delete_email` )

Удаляет электронное письмо навсегда.

{
  "messageId": "182ab45cd67ef"
}

7. Список меток электронной почты ( `list_email_labels` )

Извлекает все доступные ярлыки Gmail.

{}

8. Создать метку ( `create_label` )

Создает новый ярлык Gmail.

{
  "name": "Important Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

9. Обновить метку ( `update_label` )

Обновляет существующий ярлык Gmail.

{
  "id": "Label_1234567890",
  "name": "Urgent Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

10. Удалить метку ( `delete_label` )

Удаляет ярлык Gmail.

{
  "id": "Label_1234567890"
}

11. Получить или создать метку ( `get_or_create_label` )

Получает существующую метку по имени или создает ее, если она не существует.

{
  "name": "Project XYZ",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

12. Пакетное изменение писем ( `batch_modify_emails` )

Эффективно изменяет метки для нескольких писем пакетами.

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"],
  "batchSize": 50
}

13. Пакетное удаление писем ( `batch_delete_emails` )

Окончательно удаляет несколько писем эффективными пакетами.

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "batchSize": 50
}

Синтаксис расширенного поиска

Инструмент search_emails поддерживает мощные операторы поиска Gmail:

Оператор	Пример	Описание
`from:`	`from:john@example.com`	Письма от определенного отправителя
`to:`	`to:mary@example.com`	Письма, отправленные определенному получателю
`subject:`	`subject:"meeting notes"`	Письма с определенным текстом в теме
`has:attachment`	`has:attachment`	Письма с вложениями
`after:`	`after:2024/01/01`	Письма, полученные после свидания
`before:`	`before:2024/02/01`	Письма, полученные до даты
`is:`	`is:unread`	Письма с определенным статусом
`label:`	`label:work`	Письма с определенной меткой

Вы можете объединить несколько операторов: from:john@example.com after:2024/01/01 has:attachment

Расширенные функции

Извлечение содержимого электронной почты

Сервер интеллектуально извлекает содержимое электронной почты из сложных структур MIME:

Приоритет отдается обычному текстовому контенту, если он доступен
Возвращается к HTML-контенту, если простой текст недоступен
Обрабатывает многокомпонентные сообщения MIME с вложенными частями
Обрабатывает информацию о вложениях (имя файла, тип, размер)
Сохраняет оригинальные заголовки писем (От, Кому, Тема, Дата)

Поддержка международного характера

Сервер полностью поддерживает символы, не входящие в набор ASCII, в темах и содержимом электронных писем, включая:

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

Комплексное управление этикетками

Сервер предоставляет полный набор инструментов для управления ярлыками Gmail:

Создание меток : создание новых меток с настраиваемыми параметрами видимости.
Обновление меток : переименование меток или изменение настроек их видимости.
Удалить метки : удалить метки, созданные пользователем (системные метки защищены)
Найти или создать : получить метку по имени или автоматически создать ее, если она не найдена
Список всех меток : просмотр всех системных и пользовательских меток с подробной информацией.
Параметры видимости меток : управление отображением меток в сообщениях и списках меток.

Настройки видимости меток включают в себя:

messageListVisibility : управляет отображением метки в списке сообщений ( show или hide )
labelListVisibility : управляет тем, как отображается метка в списке меток ( labelShow , labelShowIfUnread или labelHide ).

Эти функции управления ярлыками позволяют осуществлять сложную организацию электронных писем непосредственно через Claude, без необходимости переключения на интерфейс Gmail.

Пакетные операции

Сервер включает в себя эффективные возможности пакетной обработки:

Обрабатывать до 50 писем одновременно (размер пакета можно настраивать)
Автоматическое разделение больших наборов электронных писем на части для обхода ограничений API
Подробный отчет об успехах/неудачах для каждой операции
Грамотная обработка ошибок с индивидуальными повторными попытками
Идеально подходит для управления массовыми входящими сообщениями и задач по организации

Заметки о безопасности

Учетные данные OAuth надежно хранятся в вашей локальной среде ( ~/.gmail-mcp/ )
Сервер использует автономный доступ для поддержания постоянной аутентификации.
Никогда не передавайте и не передавайте свои учетные данные в систему контроля версий.
Регулярно проверяйте и отзывайте неиспользуемый доступ в настройках вашего аккаунта Google.
Учетные данные хранятся глобально, но доступны только текущему пользователю.

Поиск неисправностей

Ключи OAuth не найдены
- Убедитесь, что gcp-oauth.keys.json находится либо в вашем текущем каталоге, либо в ~/.gmail-mcp/
- Проверьте права доступа к файлу
Неверный формат учетных данных
- Убедитесь, что ваш файл ключей OAuth содержит web или installed учетные данные.
- Для веб-приложений проверьте правильность настройки URI перенаправления.
Порт уже используется
- Если порт 3000 уже используется, освободите его перед запуском аутентификации.
- Вы можете найти и остановить процесс, используя этот порт.
Сбои пакетной обработки
- Если пакетные операции не выполняются, они автоматически повторяют отдельные элементы.
- Проверьте подробные сообщения об ошибках на предмет конкретных сбоев.
- Рассмотрите возможность уменьшения размера партии, если вы столкнулись с ограничением скорости.

Внося вклад

Вклады приветствуются! Пожалуйста, не стесняйтесь отправлять запрос на включение.

Запуск оценок

Пакет evals загружает клиент mcp, который затем запускает файл index.ts, поэтому нет необходимости перестраиваться между тестами. Вы можете загрузить переменные среды, указав префикс команды npx. Полную документацию можно найти здесь .

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/index.ts

Лицензия

Массачусетский технологический институт

Поддерживать

Если у вас возникли какие-либо проблемы или есть вопросы, пожалуйста, сообщите о проблеме в репозитории GitHub.

Integrations