Gmail Storage & Cleanup MCP

Узкоспециализированный локальный MCP-плагин для Codex и Claude Code, который отслеживает общее хранилище Google и помогает освободить место в Gmail с помощью детерминированного процесса очистки, основанного на предварительной проверке.

Он проверяет квоту хранилища Google, находит крупных кандидатов на очистку в Gmail, объясняет каждое решение о безопасности и требует подтверждения перед перемещением писем в Корзину. Он никогда не удаляет письма безвозвратно. В этот репозиторий не включены никакие учётные данные.

Зачем это нужно

Для обычной работы с входящими, например поиска писем, составления сводок по цепочкам, написания черновиков ответов, пересылки и применения меток, лучше подходит официальный плагин Gmail.

Этот проект намеренно сосредоточен на другой задаче: предотвращение исчерпания хранилища аккаунта Google без бездумного удаления важных писем.

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

Related MCP server: Gmail MCP Server

Установка

Требования: Python 3.12+, Git и учётная запись Google с Gmail.

git clone https://github.com/ashutoshchaubeypm/Gmail-MCP-tool.git
cd Gmail-MCP-tool
./scripts/setup.sh

1. Создайте учётные данные Google

В Google Cloud Console:

1. Создайте проект и включите Gmail API и Google Drive API.

2. Настройте Google Auth Platform. Для личного тестирования используйте External/Testing и добавьте свой адрес Gmail в качестве тестового пользователя.

3. Создайте OAuth-клиент с типом приложения Desktop app.

4. Откройте .env и добавьте сгенерированные значения:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

Авторизуйтесь один раз:

.venv/bin/python -m app.auth_cli

Локальный токен записывается в work/google-token.json. И он, и .env игнорируются Git.

2. Установите в Codex

Из корня репозитория:

codex plugin marketplace add "$PWD"
codex plugin add gmail-mcp-tool@personal

Начните новую задачу в Codex, а затем попросите: «Проверь моё хранилище Google и найди кандидатов на очистку Gmail для проверки».

3. Установите в Claude Code

Из корня репозитория:

claude plugin marketplace add "$PWD"
claude plugin install gmail-mcp-tool@gmail-mcp-tool

Запустите новую сессию Claude Code после установки.

Специализированные инструменты

• get_storage_quota — использование общего хранилища Google

• scan_cleanup_candidates — поиск кандидатов на очистку в Gmail в режиме только для чтения и детерминированная оценка

• get_candidate_details — просмотр одного результата последнего сканирования

• move_message_to_trash — перемещает одно подтверждённое незащищённое сообщение в Корзину

Защищённые метки включают STARRED, IMPORTANT, SENT и DRAFT. Неоднозначные письма остаются на проверке. Переместить можно только сообщение из последнего сканирования, а защищённые сообщения инструмент обработать не может. Плагин не очищает Корзину и не удаляет сообщения безвозвратно.

Разработка

.venv/bin/python scripts/security_check.py
.venv/bin/python -m pytest -q

Исходный код плагина: plugins/gmail-mcp-tool/

Сознательно ограниченная область применения

• Прогнозирование использования хранилища и проверки квоты по расписанию

• Более прозрачные политики очистки и настройка правил

• Сводные оценки освобождаемого места и отчёты об очистке

• Опциональная классификация неоднозначных кандидатов без обхода детерминированных механизмов защиты

Общий поиск по входящим, сводки писем, составление ответов и пересылка намеренно предоставлены официальному плагину Gmail.

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

Никогда не добавляйте в коммит .env, скачанный JSON-файл OAuth или work/google-token.json. Перед публикацией изменений запустите python scripts/security_check.py. Если учётные данные когда-либо попали в коммит, немедленно отзовите и перевыпустите их — удалить их из последнего коммита недостаточно.

Распространяется по лицензии MIT.