Gmail Storage & Cleanup MCP

Codex 및 Claude Code를 위한 집중형 로컬 MCP 플러그인으로, 공유 Google 저장용량을 모니터링하고 결정적이고 검토 우선의 정리 워크플로를 통해 Gmail 공간을 확보하는 데 도움을 줍니다.

Google 저장용량 할당량을 확인하고, 용량이 큰 Gmail 정리 후보를 찾아내며, 모든 안전 결정을 설명하고, 메일을 휴지통으로 옮기기 전에 확인을 요구합니다. 메일을 영구 삭제하지 않습니다. 이 저장소에는 자격 증명이 포함되어 있지 않습니다.

존재 이유

공식 Gmail 플러그인은 메일 검색, 스레드 요약, 답장 작성, 전달, 라벨 적용과 같은 일반적인 받은편지함 작업에 더 적합합니다.

이 프로젝트는 의도적으로 다른 문제에 초점을 맞춥니다: 중요한 이메일을 무작정 삭제하지 않으면서 Google 계정의 저장용량 부족을 방지하는 것.

이 비교는 각 플러그인의 문서화된 초점을 설명한 것이며, 업스트림 커넥터가 향후 추가할 수 있는 모든 기능을 설명하는 것은 아닙니다.

Related MCP server: Gmail Guardian

설치

요구 사항: Python 3.12+, Git, Gmail이 포함된 Google 계정.

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. 애플리케이션 유형이 Desktop app인 OAuth 클라이언트를 만드세요.

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, 다운로드한 OAuth JSON, work/google-token.json을 커밋하지 마세요. 변경 사항을 게시하기 전에 python scripts/security_check.py를 실행하세요. 자격 증명이 커밋된 적이 있다면 즉시 취소하고 교체하세요—최신 커밋에서 제거하는 것만으로는 충분하지 않습니다.

MIT 라이선스입니다.