Gmail Cleanup MCP Server

Сервер Model Context Protocol для очистки входящих Gmail — удаление писем в корзину, управление фильтрами и извлечение ссылок отписки. Разработан как дополнение к встроенному Gmail-коннектору Anthropic, который отвечает за чтение, поиск, черновики и отправку.

Исправленный форк dcerniglia/gmail-cleanup-mcp (лицензия MIT). Этот форк исправляет ошибку, из-за которой search_and_trash и batch_trash_emails молча игнорировали ошибки вместо повторных попыток — 50 одновременных запросов на удаление могли упереться в лимит Gmail и потерять ~половину пакета без каких-либо сообщений об ошибке. Теперь оба инструмента работают меньшими пакетами, делают паузы, автоматически повторяют попытки и сообщают реальную ошибку для каждого необработанного письма.

Инструменты

Related MCP server: Gmail AutoAuth MCP Server

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

• Node.js 18+

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

• Учётные данные OAuth 2.0 (тип приложения «Desktop»)

Настройка

1. Google Cloud OAuth

Уже есть ~/.gmail-mcp/gcp-oauth.keys.json от другого Gmail MCP-сервера? Переходите к шагу 2 — этот сервер использует то же расположение учётных данных.

1. Перейдите в Google Cloud Console

2. Создайте проект (или используйте существующий) и включите Gmail API

3. Перейдите в Credentials → Create Credentials → OAuth client ID

4. Выберите Desktop app, скачайте JSON

5. Сохраните его как ~/.gmail-mcp/gcp-oauth.keys.json (или поместите gcp-oauth.keys.json в каталог проекта — он будет скопирован автоматически при первом запуске)

2. Установка и сборка

git clone https://github.com/davidcerniglia/gmail-cleanup-mcp.git
cd gmail-cleanup-mcp
npm install
npm run build

3. Аутентификация

npm run auth

Откроется браузер для согласия Google OAuth. Учётные данные сохраняются в ~/.gmail-mcp/credentials.json с правами 0600 (только для владельца).

4. Добавление в Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Или для Claude Code добавьте в .claude/settings.json:

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

Примеры использования

Как это работает со встроенным Gmail от Claude

Безопасность

• Минимальные разрешения: gmail.modify + gmail.settings.basic — минимум, необходимый для операций с корзиной и фильтрами

• Корзина, а не удаление: все удаления используют корзину Gmail (30-дневное окно восстановления), никогда — необратимое удаление

• Режим dry-run: search_and_trash может показать совпадения до выполнения

• Ограничительные права на файлы: учётные данные хранятся с правами 0600 (чтение/запись только для владельца)

• Нет обработки вложений: нулевой риск обхода каталогов

• Нет доступа к файловой системе за пределами хранения учётных данных в ~/.gmail-mcp/

Переменные окружения

Лицензия

MIT