MCP Headless Gmail-сервер

Сервер MCP (Model Context Protocol), который обеспечивает получение и отправку писем Gmail без локальной настройки учетных данных или токена.

Почему стоит выбрать MCP Headless Gmail Server?

Критические преимущества

Автономная и удаленная работа : в отличие от других решений MCP Gmail, требующих запуска вне Docker и доступа к локальным файлам, этот сервер может работать полностью автономно в удаленных средах без браузера и доступа к локальным файлам.
Разделенная архитектура : любой клиент может независимо завершить поток OAuth, а затем передать учетные данные в качестве контекста на этот сервер MCP, создавая полное разделение между хранилищем учетных данных и реализацией сервера.

Неплохо, но не критично

Специализированная функциональность : во многих случаях использования, особенно для маркетинговых приложений, требуется только доступ к Gmail без дополнительных служб Google, таких как Календарь, что делает эту специализированную реализацию идеальной.
Docker-Ready : разработан с учетом контейнеризации для надежной изоляции, независимой от среды и настройки в один клик.
Надежные зависимости : построено на хорошо поддерживаемой библиотеке google-api-python-client.

Функции

Получайте последние письма из Gmail с первыми 1000 символами текста
Получите полный текст письма частями по 1 тыс. с помощью параметра offset
Отправка писем через Gmail
Обновите токены доступа по отдельности
Автоматическая обработка токенов обновления

Предпосылки

Python 3.10 или выше
Учетные данные API Google (идентификатор клиента, секрет клиента, токен доступа и токен обновления)

Установка

# Clone the repository
git clone https://github.com/baryhuang/mcp-headless-gmail.git
cd mcp-headless-gmail

# Install dependencies
pip install -e .

Докер

Создание образа Docker

# Build the Docker image
docker build -t mcp-headless-gmail .

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

Вы можете настроить Claude Desktop для использования образа Docker, добавив в конфигурацию Claude следующее:

докер

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "buryhuang/mcp-headless-gmail:latest"
      ]
    }
  }
}

npm-версия

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

Примечание: При такой конфигурации вам необходимо предоставить учетные данные Google API в вызовах инструментов, как показано в разделе «Использование инструментов» . Учетные данные Gmail не передаются как переменные среды для поддержания разделения между хранилищем учетных данных и реализацией сервера.

Кросс-платформенная публикация

Чтобы опубликовать образ Docker для нескольких платформ, вы можете использовать команду docker buildx . Выполните следующие действия:

Создайте новый экземпляр конструктора (если вы еще этого не сделали):
docker buildx create --use
Создайте и распространите образ на несколько платформ :
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-headless-gmail:latest --push .
Убедитесь, что изображение доступно для указанных платформ :
docker buildx imagetools inspect buryhuang/mcp-headless-gmail:latest

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

Сервер обеспечивает функциональность Gmail через инструменты MCP. Обработка аутентификации упрощается с помощью специального инструмента обновления токенов.

Запуск сервера

mcp-server-headless-gmail

Использование инструментов

При использовании MCP-клиента, такого как Claude, у вас есть два основных способа выполнения аутентификации:

Обновление токенов (первый шаг или по истечении срока действия токенов)

Если у вас есть и токены доступа, и токены обновления:

{
  "google_access_token": "your_access_token",
  "google_refresh_token": "your_refresh_token",
  "google_client_id": "your_client_id",
  "google_client_secret": "your_client_secret"
}

Если срок действия вашего токена доступа истек, вы можете обновить его, используя только токен обновления:

{
  "google_refresh_token": "your_refresh_token",
  "google_client_id": "your_client_id",
  "google_client_secret": "your_client_secret"
}

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

Получение последних писем

Извлекает последние электронные письма с первыми 1000 символами каждого текста электронного письма:

{
  "google_access_token": "your_access_token",
  "max_results": 5,
  "unread_only": false
}

Ответ включает в себя:

Метаданные электронной почты (id, threadId, от, кому, тема, дата и т. д.)
Первые 1000 символов текста письма
body_size_bytes : Общий размер тела письма в байтах.
contains_full_body : логическое значение, указывающее, включено ли все тело (true) или усечено (false)

Получение полного содержания электронного письма

Для писем, текст которых превышает 1 тыс. символов, вы можете извлечь все содержимое по частям:

{
  "google_access_token": "your_access_token",
  "message_id": "message_id_from_get_recent_emails",
  "offset": 0
}

Вы также можете получить содержимое письма по идентификатору темы:

{
  "google_access_token": "your_access_token",
  "thread_id": "thread_id_from_get_recent_emails",
  "offset": 1000
}

Ответ включает в себя:

Фрагмент текста письма размером 1 КБ, начинающийся с указанного смещения
body_size_bytes : Общий размер тела письма
chunk_size : Размер возвращаемого фрагмента
contains_full_body : логическое значение, указывающее, содержит ли фрагмент оставшуюся часть тела

Чтобы получить весь текст длинного сообщения, выполните последовательные вызовы, увеличивая смещение на 1000 каждый раз, пока contains_full_body не станет истинным.

Отправка электронного письма

{
  "google_access_token": "your_access_token",
  "to": "recipient@example.com",
  "subject": "Hello from MCP Gmail",
  "body": "This is a test email sent via MCP Gmail server",
  "html_body": "<p>This is a <strong>test email</strong> sent via MCP Gmail server</p>"
}

Рабочий процесс обновления токена

Начните с вызова инструмента gmail_refresh_token одним из следующих способов:
- Ваши полные учетные данные (токен доступа, токен обновления, идентификатор клиента и секрет клиента) или
- Только ваш токен обновления, идентификатор клиента и секретный ключ клиента, если срок действия токена доступа истек
Используйте возвращенный новый токен доступа для последующих вызовов API.
Если вы получили ответ, указывающий на истечение срока действия токена, вызовите инструмент gmail_refresh_token еще раз, чтобы получить новый токен.

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

Получение учетных данных Google API

Чтобы получить необходимые учетные данные Google API, выполните следующие действия:

Перейдите в Google Cloud Console.
Создать новый проект
Включить API Gmail
Настроить экран согласия OAuth
Создайте учетные данные идентификатора клиента OAuth (выберите «Приложение для настольного компьютера» в качестве типа приложения)
Сохраните идентификатор клиента и секрет клиента.
Используйте OAuth 2.0 для получения доступа и обновления токенов в следующих областях:
- https://www.googleapis.com/auth/gmail.readonly (для чтения писем)
- https://www.googleapis.com/auth/gmail.send (для отправки писем)

Обновление токена

Этот сервер реализует автоматическое обновление токена. Когда срок действия вашего токена доступа истекает, клиент API Google будет использовать токен обновления, идентификатор клиента и секрет клиента для получения нового токена доступа без необходимости вмешательства пользователя.

Примечание по безопасности

Этот сервер требует прямого доступа к вашим учетным данным Google API. Всегда храните свои токены и учетные данные в безопасности и никогда не делитесь ими с недоверенными сторонами.

Лицензия

Подробную информацию смотрите в файле ЛИЦЕНЗИЯ.

MCP Headless Gmail Server

Integrations