Gmail MCP Server

Сервер протокола контекста модели (MCP), предоставляющий доступ к Gmail только для чтения. Позволяет Claude Code безопасно искать, читать и анализировать ваш почтовый ящик Gmail.

Функции

• search_emails - Поиск с использованием синтаксиса запросов Gmail

• list_unread - Список непрочитанных писем

• get_message - Получение полного содержимого сообщения с метаданными вложений

• get_thread - Получение всех сообщений в цепочке переписки

• draft_reply - Подготовка содержимого черновика ответа (НЕ отправляет его)

Related MCP server: Gmail MCP Server

Предварительные требования

• Node.js 18+

• Проект Google Cloud с включенным Gmail API

• Учетные данные OAuth 2.0 для настольного приложения

Настройка Google Cloud

1. Создание проекта Google Cloud

1. Перейдите в Консоль Google Cloud

2. Нажмите "Выбрать проект" → "Новый проект"

3. Назовите проект (например, "Gmail MCP Server")

4. Нажмите "Создать"

2. Включение Gmail API

1. В своем проекте перейдите в "API и сервисы" → "Библиотека"

2. Найдите "Gmail API"

3. Нажмите на него и выберите "Включить"

3. Настройка экрана согласия OAuth

1. Перейдите в "API и сервисы" → "Экран согласия OAuth"

2. Выберите "Внешний" (или "Внутренний", если используете Google Workspace)

3. Заполните обязательные поля:

   • Название приложения: "Gmail MCP Server"

   • Электронная почта для поддержки пользователей: ваш email

   • Контактные данные разработчика: ваш email

4. Нажмите "Сохранить и продолжить"

5. Добавьте области доступа (scopes):

   • https://www.googleapis.com/auth/gmail.readonly

   • https://www.googleapis.com/auth/gmail.compose

6. Добавьте свой email в качестве тестового пользователя (если выбрано "Внешний")

7. Завершите настройку

4. Создание учетных данных OAuth

1. Перейдите в "API и сервисы" → "Учетные данные"

2. Нажмите "Создать учетные данные" → "Идентификатор клиента OAuth"

3. Выберите "Настольное приложение" в качестве типа приложения

4. Назовите его (например, "Gmail MCP Desktop")

5. Нажмите "Создать"

6. Скачайте или скопируйте идентификатор клиента (Client ID) и секрет клиента (Client Secret)

Установка

# Clone or navigate to the project
cd gmail-mcp

# Install dependencies
npm install

# Build the project
npm run build

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

1. Скопируйте пример файла окружения:

cp .env.example .env

2. Отредактируйте .env, указав свои учетные данные OAuth:

CLIENT_ID=your-client-id.apps.googleusercontent.com
CLIENT_SECRET=your-client-secret

Первый запуск (Авторизация)

При первом запуске сервера произойдет следующее:

1. Откроется браузер для авторизации в Google

2. Вам будет предложено войти в систему и предоставить разрешения

3. Токены будут сохранены локально в файле token.json

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

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

Добавление MCP-сервера

claude mcp add gmail node ./dist/index.js

Или добавьте его в конфигурацию Claude Code вручную:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/gmail-mcp"
    }
  }
}

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

search_emails

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

Query examples:
- "from:user@example.com"
- "subject:meeting"
- "is:unread"
- "after:2024/01/01 before:2024/12/31"
- "has:attachment filename:pdf"
- "in:inbox -category:promotions"

list_unread

Список непрочитанных писем (сокращение для поиска is:unread).

get_message

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

get_thread

Получение всех сообщений в цепочке переписки по ID цепочки.

draft_reply

Подготовка черновика ответа на цепочку писем. Предоставляет контекст для составления ответа, но НЕ отправляет никаких писем.

Разработка

# Run in development mode (with hot reload)
npm run dev

# Type check
npm run typecheck

# Build for production
npm run build

# Run production build
npm start

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

• Токены OAuth хранятся локально в token.json

• Никогда не добавляйте .env или token.json в систему контроля версий

• Сервер запрашивает только разрешения на чтение и создание черновиков

• Письма не отправляются — draft_reply только подготавливает содержимое

• Содержимое писем не логируется

Устранение неполадок

"Missing CLIENT_ID or CLIENT_SECRET"

Убедитесь, что ваш файл .env существует и содержит корректные учетные данные.

"Authorization timeout"

Процесс авторизации OAuth имеет тайм-аут 5 минут. Перезапустите сервер и завершите авторизацию быстрее.

"Token refresh failed"

Удалите token.json и пройдите авторизацию заново.

"Access blocked: This app's request is invalid"

Убедитесь, что ваш экран согласия OAuth настроен правильно и ваш email добавлен в качестве тестового пользователя.