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

Related MCP server: gmail-mcp

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

• Node.js 18 или выше

• npm

• Учетная запись Google с доступом к Gmail API

Установка

npm install
npm run build

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

1. Откройте Google Cloud Console.

2. Создайте или выберите проект.

3. Перейдите в APIs & Services -> Library, найдите и включите Gmail API.

4. Перейдите в APIs & Services -> OAuth consent screen.

5. Выберите тип пользователя. Для личного использования обычно выбирают External.

6. Укажите название приложения, электронную почту для поддержки пользователей и контактный адрес электронной почты разработчика.

7. На этапе Scopes добавьте разрешение Gmail «только для чтения»: https://www.googleapis.com/auth/gmail.readonly.

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

9. Перейдите в APIs & Services -> Credentials.

10. Нажмите Create Credentials -> OAuth client ID.

11. В качестве Application type выберите Desktop app.

12. После создания скачайте 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