Gmail 자동 인증 MCP 서버

Claude Desktop에서 Gmail을 통합하고 자동 인증을 지원하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버를 통해 AI 비서가 자연어 상호작용을 통해 Gmail을 관리할 수 있습니다.

특징

제목, 내용, 첨부 파일, 수신자를 지정하여 이메일을 보내세요
제목줄과 이메일 콘텐츠에서 국제 문자를 완벽하게 지원합니다.
고급 MIME 구조 처리를 통해 ID로 이메일 메시지를 읽습니다.
이메일 첨부 파일 정보(파일 이름, 유형, 크기) 보기
다양한 기준(제목, 발신자, 날짜 범위)으로 이메일 검색
레이블을 생성, 업데이트, 삭제 및 나열할 수 있는 기능을 갖춘 포괄적인 레이블 관리
사용 가능한 모든 Gmail 라벨(시스템 및 사용자 정의)을 나열합니다.
받은 편지함, 보낸 편지함 또는 사용자 지정 레이블에 이메일 나열
이메일을 읽음/읽지 않음으로 표시
이메일을 다른 라벨/폴더로 이동
이메일 삭제
여러 이메일을 동시에 효율적으로 처리하기 위한 일괄 작업
Gmail API와의 완벽한 통합
자동 브라우저 실행을 통한 간단한 OAuth2 인증 흐름
데스크톱 및 웹 애플리케이션 자격 증명 모두 지원
편의성을 위한 글로벌 자격 증명 저장

설치 및 인증

Smithery를 통해 설치

Smithery 를 통해 Claude Desktop용 Gmail AutoAuth를 자동으로 설치하려면:

지엑스피1

수동 설치

Google Cloud 프로젝트를 만들고 자격 증명을 얻으세요.a. Google Cloud 프로젝트 만들기:
- Google Cloud Console 로 이동
- 새 프로젝트를 만들거나 기존 프로젝트를 선택하세요
- 프로젝트에 Gmail API를 활성화하세요
b. OAuth 2.0 자격 증명을 생성합니다.
- "API 및 서비스" > "자격 증명"으로 이동하세요.
- "자격 증명 만들기" > "OAuth 클라이언트 ID"를 클릭하세요.
- 애플리케이션 유형으로 "데스크톱 앱" 또는 "웹 애플리케이션"을 선택하세요.
- 이름을 지정하고 "만들기"를 클릭하세요.
- 웹 애플리케이션의 경우 권한이 부여된 리디렉션 URI에 http://localhost:3000/oauth2callback 추가합니다.
- 클라이언트의 OAuth 키 JSON 파일을 다운로드하세요.
- 키 파일의 이름을 gcp-oauth.keys.json 으로 바꾸세요.
인증 실행:두 가지 방법으로 인증할 수 있습니다.a. 글로벌 인증(권장):
# First time: Place gcp-oauth.keys.json in your home directory's .gmail-mcp folder mkdir -p ~/.gmail-mcp mv gcp-oauth.keys.json ~/.gmail-mcp/ # Run authentication from anywhere npx @gongrzhe/server-gmail-autoauth-mcp auth
b. 로컬 인증:
# Place gcp-oauth.keys.json in your current directory # The file will be automatically copied to global config npx @gongrzhe/server-gmail-autoauth-mcp auth
인증 과정은 다음과 같습니다.
- 현재 디렉토리 또는 ~/.gmail-mcp/ 에서 gcp-oauth.keys.json 찾으세요.
- 현재 디렉토리에서 발견되면 ~/.gmail-mcp/ 로 복사하세요.
- Google 인증을 위해 기본 브라우저를 엽니다.
- 자격 증명을 ~/.gmail-mcp/credentials.json 으로 저장합니다.
메모 :
- 인증에 성공하면 자격 증명은 ~/.gmail-mcp/ 에 전역적으로 저장되며 모든 디렉토리에서 사용할 수 있습니다.
- 데스크톱 앱과 웹 애플리케이션 자격 증명이 모두 지원됩니다.
- 웹 애플리케이션 자격 증명의 경우 권한이 있는 리디렉션 URI에 http://localhost:3000/oauth2callback 추가해야 합니다.
Claude Desktop에서 구성:

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

도커 지원

Docker를 사용하는 것을 선호하는 경우:

입증:

docker run -i --rm \
  --mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
  -v mcp-gmail:/gmail-server \
  -e GMAIL_OAUTH_PATH=/gcp-oauth.keys.json \
  -e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \
  -p 3000:3000 \
  mcp/gmail auth

용법:

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

클라우드 서버 인증

클라우드 서버 환경(예: n8n)의 경우 인증 중에 사용자 지정 콜백 URL을 지정할 수 있습니다.

npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback

클라우드 환경 설정 지침

역방향 프록시 구성:
- 인증을 위한 포트를 노출하도록 n8n 컨테이너를 설정하세요.
- 도메인(예: gmail.gongrzhe.com )에서 이 포트로 트래픽을 전달하기 위해 역방향 프록시를 구성합니다.
DNS 구성:
- DNS 설정에 A 레코드를 추가하여 도메인을 클라우드 서버의 IP 주소로 확인하세요.
Google Cloud Platform 설정:
- Google Cloud Console에서 사용자 지정 도메인 콜백 URL(예: https://gmail.gongrzhe.com/oauth2callback )을 승인된 리디렉션 URI 목록에 추가합니다.
인증 실행:
npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback
애플리케이션에서 구성:
{ "mcpServers": { "gmail": { "command": "npx", "args": [ "@gongrzhe/server-gmail-autoauth-mcp" ] } } }

이 접근 방식을 사용하면 컨테이너화된 애플리케이션이나 클라우드 서버와 같이 로컬호스트에 액세스할 수 없는 환경에서도 인증 흐름이 제대로 작동할 수 있습니다.

사용 가능한 도구

이 서버는 Claude Desktop을 통해 사용할 수 있는 다음과 같은 도구를 제공합니다.

1. 이메일 보내기( `send_email` )

새로운 이메일을 즉시 보냅니다.

{
  "to": ["recipient@example.com"],
  "subject": "Meeting Tomorrow",
  "body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"]
}

2. 초안 이메일( `draft_email` )

이메일을 보내지 않고 임시 이메일을 작성합니다.

{
  "to": ["recipient@example.com"],
  "subject": "Draft Report",
  "body": "Here's the draft report for your review.",
  "cc": ["manager@example.com"]
}

3. 이메일 읽기( `read_email` )

ID로 특정 이메일의 내용을 검색합니다.

{
  "messageId": "182ab45cd67ef"
}

4. 이메일 검색( `search_emails` )

Gmail 검색 구문을 사용하여 이메일을 검색합니다.

{
  "query": "from:sender@example.com after:2024/01/01 has:attachment",
  "maxResults": 10
}

5. 이메일 수정( `modify_email` )

이메일에 라벨을 추가하거나 제거합니다(다른 폴더로 이동, 보관 등).

{
  "messageId": "182ab45cd67ef",
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"]
}

6. 이메일 삭제( `delete_email` )

이메일을 영구적으로 삭제합니다.

{
  "messageId": "182ab45cd67ef"
}

7. 이메일 라벨 목록( `list_email_labels` )

사용 가능한 모든 Gmail 라벨을 검색합니다.

{}

8. 라벨 생성( `create_label` )

새로운 Gmail 라벨을 만듭니다.

{
  "name": "Important Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

9. 레이블 업데이트( `update_label` )

기존 Gmail 라벨을 업데이트합니다.

{
  "id": "Label_1234567890",
  "name": "Urgent Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

10. 라벨 삭제( `delete_label` )

Gmail 라벨을 삭제합니다.

{
  "id": "Label_1234567890"
}

11. 레이블 가져오기 또는 만들기( `get_or_create_label` )

이름으로 기존 레이블을 가져오거나 레이블이 없으면 새로 만듭니다.

{
  "name": "Project XYZ",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

12. 이메일 일괄 수정( `batch_modify_emails` )

여러 이메일의 라벨을 효율적으로 일괄 처리하여 수정합니다.

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"],
  "batchSize": 50
}

13. 이메일 일괄 삭제( `batch_delete_emails` )

여러 개의 이메일을 효율적으로 일괄적으로 영구 삭제합니다.

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "batchSize": 50
}

고급 검색 구문

search_emails 도구는 Gmail의 강력한 검색 연산자를 지원합니다.

연산자	예	설명
`from:`	`from:john@example.com`	특정 발신자의 이메일
`to:`	`to:mary@example.com`	특정 수신자에게 전송된 이메일
`subject:`	`subject:"meeting notes"`	제목에 특정 텍스트가 포함된 이메일
`has:attachment`	`has:attachment`	첨부 파일이 있는 이메일
`after:`	`after:2024/01/01`	특정 날짜 이후에 수신된 이메일
`before:`	`before:2024/02/01`	날짜 전에 받은 이메일
`is:`	`is:unread`	특정 상태가 포함된 이메일
`label:`	`label:work`	특정 라벨이 있는 이메일

여러 연산자를 결합할 수 있습니다: from:john@example.com after:2024/01/01 has:attachment

고급 기능

이메일 콘텐츠 추출

서버는 복잡한 MIME 구조에서 이메일 콘텐츠를 지능적으로 추출합니다.

사용 가능한 경우 일반 텍스트 콘텐츠를 우선시합니다.
일반 텍스트를 사용할 수 없는 경우 HTML 콘텐츠로 돌아갑니다.
중첩된 부분이 있는 다중 부분 MIME 메시지를 처리합니다.
첨부 파일 정보(파일 이름, 유형, 크기)를 처리합니다.
원본 이메일 헤더(보낸 사람, 받는 사람, 제목, 날짜)를 보존합니다.

국제 문자 지원

이 서버는 다음을 포함하여 이메일 제목과 내용에서 ASCII가 아닌 문자를 완벽하게 지원합니다.

터키어, 중국어, 일본어, 한국어 및 기타 비 라틴 문자 알파벳
특수 문자 및 기호
적절한 인코딩은 이메일 클라이언트에서 올바른 표시를 보장합니다.

포괄적인 라벨 관리

이 서버는 Gmail 라벨을 관리하기 위한 완전한 도구 세트를 제공합니다.

레이블 만들기 : 사용자 정의 가능한 가시성 설정으로 새 레이블을 만듭니다.
레이블 업데이트 : 레이블 이름을 바꾸거나 표시 설정을 변경합니다.
레이블 삭제 : 사용자가 만든 레이블을 제거합니다(시스템 레이블은 보호됨)
찾기 또는 만들기 : 이름으로 레이블을 가져오거나 찾을 수 없는 경우 자동으로 만듭니다.
모든 레이블 나열 : 자세한 정보와 함께 모든 시스템 및 사용자 레이블을 봅니다.
레이블 표시 옵션 : 메시지 및 레이블 목록에 레이블이 표시되는 방식을 제어합니다.

라벨 표시 설정에는 다음이 포함됩니다.

messageListVisibility : 메시지 목록에 레이블이 나타나는지( show 또는 hide ) 여부를 제어합니다.
labelListVisibility : 레이블 목록에 레이블이 표시되는 방식( labelShow , labelShowIfUnread 또는 labelHide )을 제어합니다.

이러한 라벨 관리 기능을 사용하면 Gmail 인터페이스로 전환하지 않고도 Claude를 통해 직접 이메일을 정교하게 구성할 수 있습니다.

배치 작업

서버에는 효율적인 일괄 처리 기능이 포함되어 있습니다.

최대 50개의 이메일을 한 번에 처리합니다(배치 크기 설정 가능)
API 제한을 피하기 위해 대용량 이메일 세트를 자동으로 청킹합니다.
각 작업에 대한 자세한 성공/실패 보고
개별 재시도를 통한 우아한 오류 처리
대량 받은 편지함 관리 및 구성 작업에 적합합니다.

보안 참고 사항

OAuth 자격 증명은 로컬 환경( ~/.gmail-mcp/ )에 안전하게 저장됩니다.
서버는 오프라인 액세스를 사용하여 지속적인 인증을 유지합니다.
버전 제어에 자격 증명을 공유하거나 커밋하지 마십시오.
Google 계정 설정에서 사용하지 않는 액세스 권한을 정기적으로 검토하고 취소하세요.
자격 증명은 전역적으로 저장되지만 현재 사용자만 액세스할 수 있습니다.

문제 해결

OAuth 키를 찾을 수 없습니다
- gcp-oauth.keys.json 이 현재 디렉토리 또는 ~/.gmail-mcp/ 에 있는지 확인하세요.
- 파일 권한 확인
잘못된 자격 증명 형식
- OAuth 키 파일에 web 또는 installed 자격 증명이 포함되어 있는지 확인하세요.
- 웹 애플리케이션의 경우 리디렉션 URI가 올바르게 구성되었는지 확인하세요.
포트가 이미 사용 중입니다
- 포트 3000이 이미 사용 중이면 인증을 실행하기 전에 포트를 비워주세요.
- 해당 포트를 사용하여 프로세스를 찾아 중지할 수 있습니다.
배치 작업 실패
- 일괄 작업이 실패하면 개별 항목을 자동으로 다시 시도합니다.
- 특정 실패에 대한 자세한 오류 메시지를 확인하세요.
- 속도 제한이 발생하는 경우 배치 크기를 줄이는 것을 고려하세요.

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

특허

MIT

지원하다

문제가 발생하거나 질문이 있는 경우 GitHub 저장소에 문제를 제출하세요.

Integrations