MCP 헤드리스 Gmail 서버

로컬 자격 증명이나 토큰 설정 없이 Gmail을 받고 보낼 수 있는 MCP(Model Context Protocol) 서버입니다.

왜 MCP 헤드리스 Gmail 서버를 사용해야 하나요?

중요한 장점

헤드리스 및 원격 작업 : Docker 및 로컬 파일 액세스 외부에서 실행해야 하는 다른 MCP Gmail 솔루션과 달리 이 서버는 브라우저나 로컬 파일 액세스 없이 원격 환경에서 완전히 헤드리스로 실행될 수 있습니다.
분리된 아키텍처 : 모든 클라이언트가 OAuth 흐름을 독립적으로 완료한 다음 자격 증명을 컨텍스트로 이 MCP 서버에 전달하여 자격 증명 저장소와 서버 구현이 완전히 분리됩니다.

좋지만 비판적이지는 않음

집중된 기능 : 많은 사용 사례, 특히 마케팅 애플리케이션의 경우 캘린더와 같은 추가 Google 서비스 없이 Gmail 접속만 필요하므로 이 집중된 구현 방식이 이상적입니다.
Docker 지원 : 컨테이너화를 염두에 두고 설계되어 환경에 구애받지 않고 한 번의 클릭으로 완벽하게 격리된 설정이 가능합니다.
안정적인 종속성 : 잘 유지 관리되는 google-api-python-client 라이브러리를 기반으로 구축되었습니다.

특징

본문의 처음 1,000자까지 Gmail에서 가장 최근 이메일을 가져옵니다.
오프셋 매개변수를 사용하여 1k 청크로 전체 이메일 본문 콘텐츠를 가져옵니다.
Gmail을 통해 이메일 보내기
액세스 토큰을 별도로 새로 고침
자동 새로 고침 토큰 처리

필수 조건

Python 3.10 이상
Google API 자격 증명(클라이언트 ID, 클라이언트 비밀, 액세스 토큰 및 새로 고침 토큰)

설치

지엑스피1

도커

Docker 이미지 빌드

# Build the Docker image
docker build -t mcp-headless-gmail .

Claude Desktop과 함께 사용

Docker 사용법

Claude 구성에 다음을 추가하여 Docker 이미지를 사용하도록 Claude Desktop을 구성할 수 있습니다.

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "buryhuang/mcp-headless-gmail:latest"
      ]
    }
  }
}

참고: 이 구성을 사용하면 도구 사용 섹션에 설명된 대로 도구 호출 시 Google API 사용자 인증 정보를 제공해야 합니다. Gmail 사용자 인증 정보는 사용자 인증 정보 저장소와 서버 구현을 분리하기 위해 환경 변수로 전달되지 않습니다.

크로스 플랫폼 출판

여러 플랫폼에 Docker 이미지를 게시하려면 docker buildx 명령을 사용할 수 있습니다. 다음 단계를 따르세요.

새로운 빌더 인스턴스를 만듭니다 (아직 만들지 않았다면):
docker buildx create --use
여러 플랫폼에 대한 이미지를 빌드하고 푸시합니다 .
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-headless-gmail:latest --push .
지정된 플랫폼에서 이미지를 사용할 수 있는지 확인하세요 .
docker buildx imagetools inspect buryhuang/mcp-headless-gmail:latest

용법

이 서버는 MCP 도구를 통해 Gmail 기능을 제공합니다. 전용 토큰 새로 고침 도구를 사용하면 인증 처리가 간소화됩니다.

서버 시작

mcp-server-headless-gmail

도구 사용

Claude와 같은 MCP 클라이언트를 사용하는 경우 인증을 처리하는 두 가지 주요 방법이 있습니다.

토큰 새로 고침(첫 번째 단계 또는 토큰 만료 시)

액세스 토큰과 새로 고침 토큰이 모두 있는 경우:

{
  "google_access_token": "your_access_token",
  "google_refresh_token": "your_refresh_token",
  "google_client_id": "your_client_id",
  "google_client_secret": "your_client_secret"
}

액세스 토큰이 만료된 경우 새로 고침 토큰만으로 새로 고칠 수 있습니다.

{
  "google_refresh_token": "your_refresh_token",
  "google_client_id": "your_client_id",
  "google_client_secret": "your_client_secret"
}

이렇게 하면 새로운 액세스 토큰과 만료 시간이 반환되며, 이를 후속 호출에 사용할 수 있습니다.

최근 이메일 받기

각 이메일 본문의 처음 1,000자를 포함한 최근 이메일을 검색합니다.

{
  "google_access_token": "your_access_token",
  "max_results": 5,
  "unread_only": false
}

응답에는 다음이 포함됩니다.

이메일 메타데이터(ID, 스레드 ID, 보낸 사람, 받는 사람, 제목, 날짜 등)
이메일 본문의 처음 1000자
body_size_bytes : 이메일 본문의 총 크기(바이트)
contains_full_body : 본문 전체가 포함되는지(true) 또는 잘리는지(false)를 나타내는 부울 값입니다.

전체 이메일 본문 내용 가져오기

본문이 1,000자를 넘는 이메일의 경우 전체 내용을 청크로 검색할 수 있습니다.

{
  "google_access_token": "your_access_token",
  "message_id": "message_id_from_get_recent_emails",
  "offset": 0
}

스레드 ID로 이메일 내용을 받을 수도 있습니다.

{
  "google_access_token": "your_access_token",
  "thread_id": "thread_id_from_get_recent_emails",
  "offset": 1000
}

응답에는 다음이 포함됩니다.

지정된 오프셋에서 시작하는 이메일 본문의 1k 청크
body_size_bytes : 이메일 본문의 총 크기
chunk_size : 반환된 청크의 크기
contains_full_body : 청크에 본문의 나머지 부분이 포함되어 있는지 여부를 나타내는 부울 값입니다.

긴 메시지의 전체 이메일 본문을 검색하려면, contains_full_body 참이 될 때까지 오프셋을 1000씩 증가시키는 순차적 호출을 수행합니다.

이메일 보내기

{
  "google_access_token": "your_access_token",
  "to": "recipient@example.com",
  "subject": "Hello from MCP Gmail",
  "body": "This is a test email sent via MCP Gmail server",
  "html_body": "<p>This is a <strong>test email</strong> sent via MCP Gmail server</p>"
}

토큰 새로 고침 워크플로

다음 중 하나를 사용하여 gmail_refresh_token 도구를 호출하여 시작하세요.
- 전체 자격 증명(액세스 토큰, 새로 고침 토큰, 클라이언트 ID 및 클라이언트 비밀번호) 또는
- 액세스 토큰이 만료된 경우 새로 고침 토큰, 클라이언트 ID 및 클라이언트 비밀번호만 있으면 됩니다.
반환된 새 액세스 토큰을 후속 API 호출에 사용합니다.
토큰 만료를 나타내는 응답을 받으면 gmail_refresh_token 도구를 다시 호출하여 새로운 토큰을 받으세요.

이 접근 방식은 모든 작업에 대해 클라이언트 자격 증명을 요구하지 않고도 대부분의 API 호출을 간소화하는 동시에 필요할 때 토큰 새로 고침을 활성화합니다.

Google API 자격 증명 얻기

필요한 Google API 자격 증명을 얻으려면 다음 단계를 따르세요.

Google Cloud Console 로 이동
새 프로젝트를 만듭니다
Gmail API 활성화
OAuth 동의 화면 구성
OAuth 클라이언트 ID 자격 증명을 만듭니다(애플리케이션 유형으로 "데스크톱 앱"을 선택).
클라이언트 ID와 클라이언트 비밀번호를 저장합니다.
다음 범위의 액세스 토큰과 새로 고침 토큰을 얻으려면 OAuth 2.0을 사용하세요.
- https://www.googleapis.com/auth/gmail.readonly (이메일 읽기용)
- https://www.googleapis.com/auth/gmail.send (이메일 전송용)

토큰 새로 고침

이 서버는 토큰 자동 갱신을 구현합니다. 액세스 토큰이 만료되면 Google API 클라이언트는 갱신 토큰, 클라이언트 ID, 클라이언트 비밀번호를 사용하여 사용자 개입 없이 새 액세스 토큰을 얻습니다.

보안 참고 사항

이 서버는 Google API 사용자 인증 정보에 직접 액세스해야 합니다. 토큰과 사용자 인증 정보는 항상 안전하게 보관하고 신뢰할 수 없는 사람과 공유하지 마세요.

특허

자세한 내용은 LICENSE 파일을 참조하세요.

MCP Headless Gmail Server

Integrations