Gmail 정리 MCP 서버

이메일 정리를 위한 Model Context Protocol 서버 — 이메일 휴지통 이동, 필터 관리, 구독 취소 링크 추출 기능을 제공합니다. 이메일 검색, 읽기, 초안 작성, 보내기를 처리하는 Anthropic의 내장 Gmail 커넥터를 보완하도록 설계되었습니다.

dc/gmail-cleanup-mcp의 패치 버전 (MIT 라이선스). 이 포크는 search_and_trash 및 batch_trash_emails가 실패를 자동으로 재시도하지 않고 조용히 무시하던 버그를 수정합니다 — 동시에 50개의 휴지통 요청을 보내면 Gmail의 속도 제한에 걸려 오류 메시지 없이 약 절반의 요청이 유실될 수 있습니다. 이제 두 도구 모두 배치 크기를 줄이고, 백오프(backoff)를 적용하며, 자동 재시도하고, 실패한 각 메시지에 대해 실제 오류를 보고합니다.

도구

Related MCP server: Gmail AutoAuth MCP Server

사전 요구 사항

• Node.js 18+

• Gmail API가 활성화된 Google Cloud 프로젝트

• OAuth 2.0 자격 증명 (데스크톱 앱 유형)

설정

1. Google Cloud OAuth

이미 다른 Gmail MCP 서버에서 ~/.gmail-mcp/gcp-oauth.keys.json 파일을 가지고 있나요? 2단계로 건너뛰세요 — 이 서버는 동일한 자격 증명 위치를 사용합니다.

1. Google Cloud 콘솔로 이동

2. 프로젝트 생성 (또는 기존 프로젝트 사용) 및 Gmail API 활성화

3. 사용자 인증 정보 → 사용자 인증 정보 만들기 → OAuth 클라이언트 ID로 이동

4. 데스크톱 앱 선택, 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 동의 화면이 열립니다. 자격 증명은 0600 권한(소유자만 읽기/쓰기)으로 ~/.gmail-mcp/credentials.json에 저장됩니다.

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 커넥터와의 연동 방식

보안

• 최소 권한 범위: gmail.modify + gmail.settings.basic — 휴지통 및 필터 작업에 필요한 최소한의 권한

• 휴지통 이동, 영구 삭제 아님: 모든 삭제 작업은 Gmail의 휴지통(30일 복구 기간)을 사용하며, 영구 삭제는 절대 수행하지 않습니다

• 시험 실행 모드: search_and_trash는 실행 전에 일치 항목을 미리 볼 수 있습니다

• 제한적인 파일 권한: 자격 증명은 0600 권한(소유자만 읽기/쓰기)으로 저장됩니다

• 첨부 파일 미처리: 첨부 파일을 다루지 않아 경로 탐색(path traversal) 위험이 없습니다

• 파일 시스템 접근 없음: ~/.gmail-mcp/의 자격 증명 저장 외에는 파일 시스템에 접근하지 않습니다

환경 변수

라이선스

MIT