Gmail MCP Server

Gmail MCP Server — это MCP stdio-сервер на базе Node.js/TypeScript, предназначенный для того, чтобы OpenClaw мог читать письма Gmail через протокол Model Context Protocol.

Функции

Использование авторизации Gmail API OAuth 2.0 с областью доступа «только для чтения»: https://www.googleapis.com/auth/gmail.readonly
list_emails: перечисление писем во входящих, поддержка maxResults и фильтрации по запросу Gmail query
get_email: чтение подробностей одного письма по messageId
search_emails: поиск писем с использованием синтаксиса поиска Gmail
list_labels: перечисление всех меток/папок Gmail
Поддержка транспорта MCP stdio для вызова из OpenClaw

Системные требования

Node.js 18 или выше
npm
Учетная запись Google с доступом к Gmail API

Установка

npm install
npm run build

Создание учетных данных OAuth в Google Cloud Console

Откройте Google Cloud Console.
Создайте или выберите проект.
Перейдите в APIs & Services -> Library, найдите и включите Gmail API.
Перейдите в APIs & Services -> OAuth consent screen.
Выберите тип пользователя. Для личного использования обычно выбирают External.
Укажите название приложения, электронную почту для поддержки пользователей и контактный адрес электронной почты разработчика.
На этапе Scopes добавьте разрешение Gmail «только для чтения»: https://www.googleapis.com/auth/gmail.readonly.
Если приложение находится в статусе Testing, добавьте свою учетную запись Gmail в список Test users.
Перейдите в APIs & Services -> Credentials.
Нажмите Create Credentials -> OAuth client ID.
В качестве Application type выберите Desktop app.
После создания скачайте JSON-файл.

Размещение credentials.json

Создайте каталог конфигурации и сохраните скачанный OAuth JSON как:

mkdir -p ~/.gmail-mcp
chmod 700 ~/.gmail-mcp
cp /path/to/downloaded/client_secret.json ~/.gmail-mcp/credentials.json
chmod 600 ~/.gmail-mcp/credentials.json

Итоговый путь должен выглядеть так:

~/.gmail-mcp/credentials.json

Запуск процесса авторизации

npm run auth

Скрипт выполнит следующие действия:

Запустит временный локальный сервис обратного вызова OAuth
Откроет браузер для авторизации в Google
После завершения авторизации сохранит токен в ~/.gmail-mcp/token.json

Если браузер не открылся автоматически, терминал выведет URL для авторизации, который нужно скопировать в браузер вручную.

Запуск MCP Server

npm run start

Команда start использует транспорт stdio и обычно запускается OpenClaw как дочерний процесс MCP-сервера, поэтому ручной запуск на длительное время не требуется.

Пример конфигурации OpenClaw MCP

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

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/Volumes/DevDisk/symbol/gmailMCP/dist/src/index.js"]
    }
  }
}

Также можно запустить через npm в каталоге проекта:

{
  "mcpServers": {
    "gmail": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/Volumes/DevDisk/symbol/gmailMCP"
    }
  }
}

Описание параметров инструментов

list_emails

Перечисление писем во входящих.

{
  "maxResults": 10,
  "query": "from:example@gmail.com newer_than:7d"
}

maxResults: необязательно, по умолчанию 10, максимум 50
query: необязательно, синтаксис поиска Gmail, поиск будет ограничен папкой INBOX

get_email

Чтение подробностей одного письма.

{
  "messageId": "18f..."
}

Возвращаемые поля включают отправителя, получателя, тему, дату, метки, текстовое тело, HTML-тело и метаданные вложений.

search_emails

Поиск писем в Gmail.

{
  "query": "subject:invoice has:attachment newer_than:30d",
  "maxResults": 10
}

query: обязательно, поддерживает синтаксис поиска Gmail
maxResults: необязательно, по умолчанию 10, максимум 50

list_labels

Перечисление всех меток/папок.

{}

Расположение файлов

Учетные данные OAuth: ~/.gmail-mcp/credentials.json
Токен OAuth: ~/.gmail-mcp/token.json
Точка входа MCP-сервера: dist/src/index.js

Часто задаваемые вопросы

Отсутствуют учетные данные Gmail OAuth

Убедитесь, что вы скачали JSON-файл клиента Google OAuth и сохранили его по пути:

~/.gmail-mcp/credentials.json

Отсутствует токен Gmail OAuth

Сначала запустите:

npm run auth

access_denied или приложение не подтверждено

Если экран согласия OAuth все еще находится в статусе Testing, необходимо добавить текущую учетную запись Gmail в список Test users.

invalid_grant

Удалите старый токен и пройдите авторизацию заново:

rm ~/.gmail-mcp/token.json
npm run auth

gmail-mcp