Gmail

Gmail MCP 서버는 Model Context Protocol을 통해 Claude와 같은 AI 어시스턴트가 Gmail 계정과 상호작용할 수 있게 해주는 통합 인터페이스입니다. 이를 통해 AI 어시스턴트는 자연어 명령으로 이메일을 보내고, 읽고, 검색하고, 관리할 수 있습니다.

특징

• 이메일 전송: 제목, 내용, 첨부 파일, 수신자(To, CC, BCC) 지정 가능
• 이메일 검색: 보낸 사람, 날짜 범위, 제목 등 다양한 조건으로 검색
• 이메일 읽기: ID로 특정 이메일 내용 조회 및 고급 MIME 구조 처리
• 첨부파일 관리: 파일명, 유형, 크기 등 첨부 파일 정보 조회
• 레이블 관리: 시스템 및 사용자 정의 레이블 생성, 조회, 업데이트, 삭제
• 자동 인증: OAuth 2.0을 통한 자동 인증 및 토큰 저장
• 국제 문자 지원: 제목과 이메일 내용에 국제 문자 완벽 지원
• 배치 처리: 최대 50개 이메일 일괄 처리(API 제한 방지를 위한 자동 청크 처리)

API

리소스

• Messages: 이메일 메시지 정보(제목, 내용, 발신자, 수신자, 첨부 파일 등)
• Labels: 이메일 분류를 위한 레이블(시스템 레이블 및 사용자 정의 레이블)
• Attachments: 이메일에 첨부된 파일
• Drafts: 저장된 이메일 초안
• Profile: 사용자 Gmail 프로필 정보

도구

read_gmail_profile

사용자의 Gmail 프로필 정보를 조회합니다. - 입력: 없음

search_gmail_messages

지정된 검색 조건에 맞는 Gmail 메시지를 검색합니다. - 입력: - q: Gmail 검색 구문을 사용한 검색 질의(선택) - page_token: 페이지네이션 토큰(선택)

read_gmail_thread

특정 이메일 스레드의 전체 내용을 읽습니다. - 입력: - thread_id: 읽을 스레드 ID - include_full_messages: 전체 메시지 내용 포함 여부(기본값: true)

read_gmail_message

특정 이메일 메시지의 내용을 읽습니다. - 입력: - message_id: 읽을 메시지 ID

send_email

새 이메일을 작성하여 전송합니다. - 입력: - to: 수신자 이메일 주소(배열) - subject: 이메일 제목 - body: 이메일 본문 - cc: 참조 수신자(배열, 선택) - bcc: 숨은 참조 수신자(배열, 선택) - attachments: 첨부 파일(선택)

create_draft

이메일 초안을 작성하여 저장합니다. - 입력: - to: 수신자 이메일 주소(배열) - subject: 이메일 제목 - body: 이메일 본문 - cc: 참조 수신자(배열, 선택) - bcc: 숨은 참조 수신자(배열, 선택)

list_labels

사용자의 모든 Gmail 레이블을 조회합니다. - 입력: 없음

create_label

새로운 Gmail 레이블을 생성합니다. - 입력: - name: 레이블 이름 - labelListVisibility: 레이블 표시 설정(선택) - messageListVisibility: 메시지 목록 표시 설정(선택)

update_label

기존 Gmail 레이블을 업데이트합니다. - 입력: - id: 업데이트할 레이블 ID - name: 새 레이블 이름(선택) - labelListVisibility: 레이블 표시 설정(선택) - messageListVisibility: 메시지 목록 표시 설정(선택)

delete_label

Gmail 레이블을 삭제합니다. - 입력: - id: 삭제할 레이블 ID

modify_message_labels

메시지에 레이블을 추가하거나 제거합니다. - 입력: - id: 수정할 메시지 ID - addLabelIds: 추가할 레이블 ID 목록(선택) - removeLabelIds: 제거할 레이블 ID 목록(선택)

사용 방법

설치 및 구성

1. Google Cloud Console에서 프로젝트 생성 및 Gmail API 활성화
2. OAuth 2.0 인증 자격 증명 설정
3. 애플리케이션 유형으로 'Desktop app' 또는 'Web application' 선택
4. Web application의 경우 http://localhost:3000/oauth2callback을 승인된 리디렉션 URI로 추가
5. 생성된 gcp-oauth.keys.json 파일 다운로드
6. MCP 서버 설치 및 구성
7. NPM 패키지 설치: npm install @gongrzhe/server-gmail-autoauth-mcp
8. gcp-oauth.keys.json을 홈 디렉토리의 .gmail-mcp 폴더에 배치:

   mkdir -p ~/.gmail-mcp
   mv gcp-oauth.keys.json ~/.gmail-mcp/

9. 인증 실행: npx @gongrzhe/server-gmail-autoauth-mcp auth
10. Claude Desktop 구성 파일에 MCP 서버 추가

    {
      "mcpServers": {
        "gmail": {
          "command": "npx",
          "args": ["@gongrzhe/server-gmail-autoauth-mcp"]
        }
      }
    }

11. 도커를 사용하는 경우 구성 예:

    {
      "mcpServers": {
        "gmail": {
          "command": "docker",
          "args": [
            "run", "-i", "--rm",
            "-v", "mcp-gmail:/gmail-server",
            "-e", "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json",
            "mcp/gmail"
          ]
        }
      }
    }

필요한 OAuth 스코프

• https://www.googleapis.com/auth/gmail.readonly: 이메일 읽기
• https://www.googleapis.com/auth/gmail.send: 이메일 전송
• https://www.googleapis.com/auth/gmail.compose: 이메일 작성
• https://www.googleapis.com/auth/gmail.modify: 이메일 수정(레이블 추가/제거)
• https://www.googleapis.com/auth/gmail.labels: 레이블 관리

주의사항

• 테스트 모드에서는 인증 토큰이 7일 후 만료됨
• 프로덕션 환경에서는 Google의 OAuth 애플리케이션 검증을 고려해야 함
• 인증 후 토큰은 ~/.gmail-mcp/credentials.json에 저장되며 모든 디렉토리에서 사용 가능
• Web application 자격 증명 사용 시 http://localhost:3000/oauth2callback을 승인된 리디렉션 URI로 반드시 추가해야 함

연결된 구성 요소

• Google Calendar
• Google Drive
• Time