Gmail MCP

Gmail IMAP MCP 서버

IMAP을 이용한 Gmail 통합을 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버를 통해 AI 비서가 Gmail 계정과 상호작용하여 이메일을 읽고, 검색하고, 관리하는 기능을 제공할 수 있습니다.

특징

Gmail을 사용한 OAuth2 인증
고급 검색 기능을 사용하여 Gmail 계정에서 이메일을 읽어보세요.
포괄적인 필터링(날짜, 라벨, 키워드 등)을 통해 이메일을 검색합니다.
연락처 양식 이메일에 대한 특별 처리
추가 필터링 옵션을 사용하여 읽지 않은 이메일 보기
첨부 파일이 있는 이메일 보내기
라벨 관리(생성, 삭제, 목록)
라벨 간에 이메일 이동
첨부 파일 다운로드
이메일을 읽음/읽지 않음으로 표시
여러 Gmail 계정 지원
MCP를 통한 AI 어시스턴트와의 통합
더 나은 Claude 호환성을 위한 백틱 처리

필수 조건

Gmail IMAP MCP 서버를 실행하기 전에 다음 사항이 있는지 확인하세요.

Python 3.12 이상
Gmail API가 활성화된 Google Cloud 프로젝트
OAuth 2.0 클라이언트 ID 자격 증명

설치

소스에서 설치

저장소를 복제합니다.지엑스피1
가상 환경을 만들고 활성화하세요.
python -m venv .venv # On Windows .venv\Scripts\activate # On Unix/MacOS source .venv/bin/activate
패키지를 설치하세요:
pip install -e .

Google Cloud 프로젝트 설정

Google Cloud Console 로 이동
새 프로젝트를 만들거나 기존 프로젝트를 선택하세요
프로젝트에 Gmail API를 활성화하세요.
- "API 및 서비스" > "라이브러리"로 이동합니다.
- "Gmail API"를 검색하여 활성화하세요.
OAuth 2.0 자격 증명을 만듭니다.
- "API 및 서비스" > "자격 증명"으로 이동하세요.
- "자격 증명 만들기" > "OAuth 클라이언트 ID"를 클릭하세요.
- 애플리케이션 유형으로 "데스크톱 앱"을 선택하세요
- 클라이언트 구성 파일을 다운로드하세요
다운로드한 파일을 자격 증명 디렉토리에 client_secret.json 으로 저장합니다.
mkdir -p ~/.gmail_imap_mcp_credentials # Move the downloaded file to ~/.gmail_imap_mcp_credentials/client_secret.json

최근 개선 사항

향상된 검색 기능

Gmail IMAP MCP 서버의 검색 기능이 크게 향상되었습니다.

Gmail 스타일 쿼리 구문 : from:example@gmail.com is:unread has:attachment 와 같은 Gmail 스타일 쿼리를 사용하세요.
특수 문자 지원 : 특수 문자가 포함된 레이블 쿼리(예: label:$$$$$ )
날짜 범위 필터링 : after_date 및 before_date 매개변수를 사용하여 날짜 범위별로 이메일 검색
결합 필터링 : 정확한 이메일 필터링을 위해 검색 기준을 혼합하고 일치시킵니다.
추가 검색 매개변수 : 읽음/읽지 않음 상태, 첨부 파일 등으로 필터링합니다.

문의 양식 이메일 처리

연락처 양식에서 보낸 이메일에 대한 특별 처리:

자동 감지 : 웹사이트 연락처 양식에서 보낸 이메일을 식별합니다.
실제 발신자 추출 : 회신 헤더 또는 내장된 발신자 줄에서 실제 발신자를 추출합니다.
웹사이트 소스 식별 : 연락처 양식이 어떤 웹사이트에서 왔는지 보여줍니다.
깨끗한 메시지 추출 : 양식 메타데이터를 제거하고 메시지 내용만 추출합니다.
개선된 표시 형식 : 연락처 양식 이메일을 명확하고 체계적인 형식으로 표시합니다.

백틱 JSON 처리

JSON에서 백틱을 사용하는 Claude의 경향을 처리하기 위한 지원이 추가되었습니다.

자동 변환 : 백틱으로 포맷된 JSON( name )을 적절한 JSON("name")으로 변환합니다.
오류 처리 : JSON 형식 문제에 대한 유용한 오류 메시지를 제공합니다.
원활한 통합 : 자동으로 작동하며 특별한 처리가 필요하지 않습니다.

클로드 데스크톱 가이드

이 섹션에서는 Gmail MCP 서버를 사용할 때 Claude Desktop에 대한 구체적인 지침을 제공합니다. 효과적인 이메일 처리를 위한 주요 도구와 모범 사례를 강조합니다.

주요 도구 및 기능

1. 답변 기능(중요)

두 가지의 서로 다른 회신 기능이 있으며, 각각 특정 목적에 따라 사용됩니다.

reply-to-message : 이전에 주고받은 적이 없는 새로 도착한 이메일에 답하기 위해 사용합니다.
reply-to-thread : 이미 주고받는 대화가 있는 경우 대화를 이어가기 위해 사용합니다.

중요 : 항상 적절한 답변 기능을 사용하세요.

새 메시지에 대한 초기 응답에는 reply-to-message 사용하세요.
기존 대화를 계속하려면 reply-to-thread 사용하세요.
대신 send-email 사용하면 이메일 스레드가 끊어지고 대화가 끊깁니다.

2. 이메일 콘텐츠 검색

get-email : 이 도구를 사용하면 본문, 헤더, 연락처 양식의 실제 발신자 정보를 포함한 전체 이메일 내용을 검색한 후 응답할 수 있습니다.

클로드를 위한 모범 사례

항상 전체 이메일 내용을 확인하세요 : 답장하기 전에 항상 get-email 사용하여 실제 발신자 정보를 포함한 전체 메시지를 확인하세요.
적절한 답장 기능 사용 : 기존 이메일에 답장할 때는 절대로 send-email 사용하지 마세요. 스레드를 끊기니까요. 대신 적절한 답장 기능을 사용하세요.
연락처 양식을 올바르게 처리하세요 . 연락처 양식을 제출할 때 get-email 에서 보낸 이메일 콘텐츠에 실제 발신자 정보가 있는지 확인하세요.
이메일을 읽음으로 표시 : 중복 응답을 피하기 위해 이메일을 처리한 후에는 항상 이메일을 읽음으로 표시하세요.
스레드 관리 : 기존 대화를 이어갈 때 적절한 이메일 스레드를 유지하려면 reply-to-thread 사용하세요.

특별한 경우

문의 양식 이메일

연락처 양식 이메일을 처리할 때:

향상된 파서가 제공하는 "실제 발신자" 정보를 찾으세요.
양식 제출 주소가 아닌 실제 발신자에게 답장하세요.
사업을 대표하는 만큼 적절한 전문적인 톤을 유지하십시오.

이메일 ID 및 리소스 URI

이메일 ID를 사용할 때 두 가지 형식을 접할 수 있습니다.

원시 ID(예: 12345 )
리소스 URI(예: email://message/account_INBOX_12345 )

모든 도구가 두 형식을 올바르게 처리할 수 있도록 업데이트되었습니다.

권장 워크플로

get-unread-emails 사용하여 읽지 않은 이메일을 검색하세요.
읽지 않은 각 이메일에 대해 get-email 사용하여 전체 콘텐츠를 검색합니다.
이것이 새로운 대화인지 아니면 기존 스레드의 연속인지 확인하세요.
적절한 답변 기능( reply-to-message 또는 reply-to-thread )을 사용하세요.
mark-as-read 사용하여 이메일을 읽음으로 표시하세요.

클로드의 주된 업무는 새로운 대화를 시작하는 것이 아니라 이메일에 제대로 답장하는 것입니다. 항상 올바른 답장 기능을 사용하여 이메일 스레드를 원활하게 유지하세요!

도구 참조

입증

authenticate-gmail : MCP 사용을 위해 Gmail 계정 인증

이메일 검색

search-emails : 고급 필터링으로 이메일 검색
get-unread-emails : 추가 필터링 옵션을 사용하여 읽지 않은 이메일 가져오기
get-email : 특정 이메일의 전체 세부 정보를 가져옵니다.

이메일 전송

send-email : 선택적인 첨부파일을 포함한 새 이메일을 보냅니다.
reply-to-message : 특정 이메일에 답장
reply-to-thread : 이메일 스레드(최근 메시지)에 답장

라벨 관리

list-labels : 사용 가능한 모든 레이블을 나열합니다.
create-label : 새 라벨을 만듭니다
delete-label : 기존 라벨을 삭제합니다.
move-email : 라벨 간에 이메일 이동

이메일 구성

download-attachment : 이메일 첨부 파일 다운로드
mark-as-read : 이메일을 읽음으로 표시
mark-as-unread : 이메일을 읽지 않음으로 표시

고급 사용 예

날짜 범위 및 레이블을 사용한 향상된 검색

{
  "name": "search-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "mailbox": "$$$$$",
    "query": "important project",
    "after_date": "2023/01/01",
    "before_date": "2023/12/31",
    "is_unread": true,
    "limit": 20
  }
}

추가 필터링을 통해 읽지 않은 이메일 가져오기

{
  "name": "get-unread-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "mailbox": "$$$$$",
    "additional_query": "client meeting",
    "after_date": "2023/06/01",
    "limit": 10
  }
}

복잡한 Gmail 쿼리로 검색

{
  "name": "search-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "query": "from:client@example.com has:attachment -in:trash",
    "limit": 15
  }
}

아키텍처 및 구현 세부 정보

자격 증명 저장소

Gmail IMAP MCP 서버는 OAuth2 자격 증명을 사용자 홈 디렉터리인 ~/.gmail_imap_mcp_credentials/ 에 저장합니다. 이 접근 방식은 다음과 같은 여러 장점을 제공합니다.

보안 : 자격 증명은 애플리케이션 디렉토리가 아닌 사용자별 위치에 저장됩니다.
지속성 : 자격 증명은 여러 세션과 애플리케이션 재시작 시에도 유지됩니다.
호환성 : 읽기 전용 파일 시스템에서 권한 문제를 방지합니다.

자격 증명 디렉토리에는 다음이 포함됩니다.

client_secret.json : Google Cloud Console의 OAuth 클라이언트 자격 증명
인증된 각 Gmail 계정에 대한 토큰 파일(형식: token_{email_address}.json )

IMAP 구현

이 서버는 Gmail의 IMAP 작업에 Python의 imaplib2 라이브러리를 사용합니다. 주요 구현 세부 정보는 다음과 같습니다.

연결 : Gmail의 IMAP 서버( imap.gmail.com )에 포트 993으로 안전하게 연결
인증 : XOAUTH2 메커니즘을 사용한 OAuth2 인증
이메일 검색 : 이메일은 RFC822 형식을 사용하여 검색되고 Python의 email 모듈로 구문 분석됩니다.
라벨 관리 : Gmail 라벨은 IMAP 사서함 작업을 통해 관리됩니다.
Gmail 쿼리 구문 분석 : Gmail 스타일 쿼리는 지능적으로 IMAP 검색 기준으로 변환됩니다.

이메일 ID 형식

시스템의 이메일 ID는 다음 형식을 따릅니다.

email://message/{account}_{mailbox}_{id}

어디:

{account} : Gmail 계정 주소
{mailbox} : 이메일이 포함된 사서함/레이블
{id} : 이메일의 고유 IMAP ID

이 형식을 사용하면 시스템이 여러 계정과 사서함에서 이메일을 고유하게 식별할 수 있습니다.

기여하다

Gmail IMAP MCP 서버 개선을 위한 여러분의 참여를 환영합니다! 문제 제기나 풀 리퀘스트를 자유롭게 남겨주세요.

용법

서버 시작

Gmail IMAP MCP 서버를 실행합니다.

gmail-imap-mcp

Gmail 계정 인증

이메일 주소로 authenticate-gmail 도구를 사용하세요
브라우저에서 OAuth2 인증 흐름을 따르세요
인증되면 서버는 나중에 사용할 수 있도록 자격 증명을 저장합니다.

사용 가능한 도구 및 예

Gmail IMAP MCP 서버는 Gmail 계정과 상호 작용하기 위한 포괄적인 도구 세트를 제공합니다. 사용 가능한 모든 도구의 자세한 목록과 사용 방법 예시는 다음과 같습니다.

입증

1. 인증-gmail

MCP 서버에서 사용할 Gmail 계정을 인증합니다.

매개변수:

email : 인증을 위한 이메일 주소

예:

{
  "name": "authenticate-gmail",
  "arguments": {
    "email": "your.email@gmail.com"
  }
}

이메일 검색 및 검색

2. 검색-이메일

다양한 검색 기준을 사용하여 Gmail 계정에서 이메일을 검색합니다.

매개변수:

account : 검색할 이메일 계정
mailbox : 검색할 사서함 (기본값: INBOX)
query : 검색 쿼리
limit : 반환할 이메일의 최대 개수(기본값: 10)

예 - 특정 발신자의 이메일 검색:

{
  "name": "search-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "mailbox": "INBOX",
    "query": "from:sender@example.com",
    "limit": 5
  }
}

예 - 특정 제목의 이메일 검색:

{
  "name": "search-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "query": "subject:\"Meeting Invitation\""
  }
}

예 - 본문에 특정 텍스트가 포함된 이메일 검색:

{
  "name": "search-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "query": "TEXT \"project update\""
  }
}

3. 읽지 않은 이메일 가져오기

Gmail 계정에서 읽지 않은 이메일을 받으세요.

매개변수:

account : 이메일을 받을 이메일 계정
mailbox : 이메일을 받을 사서함(기본값: INBOX)
limit : 반환할 이메일의 최대 개수(기본값: 10)

예:

{
  "name": "get-unread-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "limit": 20
  }
}

이메일 작성 및 발송

4. 이메일 보내기

Gmail 계정에서 선택적인 첨부 파일과 HTML 콘텐츠를 포함한 이메일을 보냅니다.

매개변수:

account : 보낼 이메일 계정
to : 수신자 이메일 주소(여러 개일 경우 쉼표로 구분)
subject : 이메일 제목
body : 일반 텍스트 이메일 본문
cc : 참조 수신자(선택 사항)
bcc : 숨은 참조 수신자(선택 사항)
html_body : 이메일 본문의 HTML 버전(선택 사항)
attachments : 첨부 파일 객체 목록(선택 사항)
- 각 첨부 파일 개체에는 다음이 필요합니다.
  - path : 파일 경로
  - filename : 사용자 정의 파일 이름(선택 사항)
  - content_type : MIME 유형(선택 사항)

예시 - 간단한 이메일:

{
  "name": "send-email",
  "arguments": {
    "account": "your.email@gmail.com",
    "to": "recipient@example.com",
    "subject": "Hello from Gmail MCP",
    "body": "This is a test email sent via the Gmail IMAP MCP server."
  }
}

예 - CC, BCC 및 HTML 콘텐츠가 포함된 이메일:

{
  "name": "send-email",
  "arguments": {
    "account": "your.email@gmail.com",
    "to": "recipient@example.com",
    "subject": "Meeting Agenda",
    "body": "Please find the agenda for our upcoming meeting.",
    "cc": "manager@example.com",
    "bcc": "archive@example.com",
    "html_body": "<h1>Meeting Agenda</h1><p>Please find the agenda for our <b>upcoming meeting</b>.</p>"
  }
}

예시 - 첨부 파일이 있는 이메일:

{
  "name": "send-email",
  "arguments": {
    "account": "your.email@gmail.com",
    "to": "recipient@example.com",
    "subject": "Document Attached",
    "body": "Please find the attached document.",
    "attachments": [
      {
        "path": "/path/to/document.pdf",
        "filename": "important_document.pdf",
        "content_type": "application/pdf"
      }
    ]
  }
}

5. 메시지에 대한 답장

선택적 첨부 파일과 HTML 콘텐츠를 포함하여 특정 이메일 메시지에 답장합니다.

매개변수:

account : 답장을 보낼 이메일 계정
email_id : 회신할 이메일 ID (형식: email://message/{account}_{mailbox}_{id} 또는 raw ID)
body : 일반 텍스트 답변 본문
mailbox : 이메일이 들어있는 사서함(기본값: INBOX)
html_body : 답변의 HTML 버전(선택 사항)
attachments : 첨부 파일 객체 목록(선택 사항)
- 각 첨부 파일 개체에는 다음이 필요합니다.
  - path : 파일 경로
  - filename : 사용자 정의 파일 이름(선택 사항)
  - content_type : MIME 유형(선택 사항)

예시 - 간단한 답변:

{
  "name": "reply-to-message",
  "arguments": {
    "account": "your.email@gmail.com",
    "email_id": "email://message/your.email@gmail.com_INBOX_12345",
    "body": "Thanks for your email. I'll review your proposal and get back to you soon."
  }
}

예시 - 첨부 파일을 첨부하여 답장:

{
  "name": "reply-to-message",
  "arguments": {
    "account": "your.email@gmail.com",
    "email_id": "email://message/your.email@gmail.com_INBOX_12345",
    "body": "Please find my feedback attached.",
    "html_body": "<p>Please find my <b>feedback</b> attached.</p>",
    "attachments": [
      {
        "path": "/path/to/feedback.pdf",
        "filename": "project_feedback.pdf"
      }
    ]
  }
}

6. 스레드에 대한 답변

이메일 스레드에 답장합니다(스레드에서 가장 최근의 메시지를 사용). 선택적인 첨부 파일과 HTML 콘텐츠도 가능합니다.

매개변수:

account : 답장을 보낼 이메일 계정
thread_id : 회신할 스레드 ID (형식: email://message/{account}_{mailbox}_{id} 또는 raw ID)
body : 일반 텍스트 답변 본문
mailbox : 스레드가 포함된 사서함(기본값: INBOX)
html_body : 답변의 HTML 버전(선택 사항)
attachments : 첨부 파일 객체 목록(선택 사항)
- 각 첨부 파일 개체에는 다음이 필요합니다.
  - path : 파일 경로
  - filename : 사용자 정의 파일 이름(선택 사항)
  - content_type : MIME 유형(선택 사항)

예 - 간단한 스레드 답변:

{
  "name": "reply-to-thread",
  "arguments": {
    "account": "your.email@gmail.com",
    "thread_id": "email://message/your.email@gmail.com_INBOX_12345",
    "body": "Let's continue this discussion in our meeting tomorrow."
  }
}

라벨 관리

7. 라벨 생성

Gmail 계정에서 새로운 라벨/사서함을 만듭니다.

매개변수:

account : 라벨을 생성할 이메일 계정
label_name : 생성할 라벨의 이름

예:

{
  "name": "create-label",
  "arguments": {
    "account": "your.email@gmail.com",
    "label_name": "ProjectX"
  }
}

8. 레이블 삭제

Gmail 계정에서 라벨/사서함을 삭제합니다.

매개변수:

account : 라벨을 삭제할 이메일 계정
label_name : 삭제할 라벨의 이름

예:

{
  "name": "delete-label",
  "arguments": {
    "account": "your.email@gmail.com",
    "label_name": "OldProject"
  }
}

9. 리스트-레이블

Gmail 계정의 모든 라벨/사서함을 나열합니다.

매개변수:

account : 라벨을 나열할 이메일 계정

예:

{
  "name": "list-labels",
  "arguments": {
    "account": "your.email@gmail.com"
  }
}

이메일 구성

10. 이동-이메일

이메일을 한 라벨/사서함에서 다른 라벨/사서함으로 이동합니다.

매개변수:

account : 이메일 계정
email_id : 이동할 이메일 ID (형식: email://message/{account}_{mailbox}_{id} )
source_mailbox : 소스 사서함
target_mailbox : 대상 사서함

예:

{
  "name": "move-email",
  "arguments": {
    "account": "your.email@gmail.com",
    "email_id": "email://message/your.email@gmail.com_INBOX_12345",
    "source_mailbox": "INBOX",
    "target_mailbox": "ProjectX"
  }
}

첨부 파일 처리

11. 다운로드-첨부파일

이메일에서 첨부 파일을 다운로드합니다.

매개변수:

account : 이메일 계정
email_id : 이메일 ID (형식: email://message/{account}_{mailbox}_{id} )
attachment_index : 다운로드할 첨부 파일의 인덱스(0부터 시작)
mailbox : 이메일이 들어있는 사서함(기본값: INBOX)
download_dir : 첨부 파일을 저장할 디렉토리(기본값: "downloads")

예:

{
  "name": "download-attachment",
  "arguments": {
    "account": "your.email@gmail.com",
    "email_id": "email://message/your.email@gmail.com_INBOX_12345",
    "attachment_index": 0,
    "download_dir": "my_attachments"
  }
}

이메일 상태 관리

12. 읽음으로 표시

이메일을 읽음으로 표시하세요.

매개변수:

account : 이메일 계정
email_id : 이메일 ID (형식: email://message/{account}_{mailbox}_{id} )
mailbox : 이메일이 들어있는 사서함(기본값: INBOX)

예:

{
  "name": "mark-as-read",
  "arguments": {
    "account": "your.email@gmail.com",
    "email_id": "email://message/your.email@gmail.com_INBOX_12345"
  }
}

13. 읽지 않음으로 표시

이메일을 읽지 않음으로 표시합니다.

매개변수:

account : 이메일 계정
email_id : 이메일 ID (형식: email://message/{account}_{mailbox}_{id} )
mailbox : 이메일이 들어있는 사서함(기본값: INBOX)

예:

{
  "name": "mark-as-unread",
  "arguments": {
    "account": "your.email@gmail.com",
    "email_id": "email://message/your.email@gmail.com_INBOX_12345"
  }
}

사용 가능한 프롬프트

서버는 AI 도우미가 사용할 수 있는 다음과 같은 프롬프트를 제공합니다.

1. 요약 이메일

최근 이메일 요약을 만듭니다.

매개변수:

account : 요약할 이메일 계정
mailbox : 요약할 사서함(기본값: INBOX)
count : 요약할 이메일 수 (기본값: 5)

예:

{
  "name": "summarize-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "mailbox": "INBOX",
    "count": 10
  }
}

AI 어시스턴트와의 통합

Gmail IMAP MCP 서버는 모델 컨텍스트 프로토콜(MCP)을 지원하는 AI 어시스턴트와 통합될 수 있습니다. 일반적인 워크플로는 다음과 같습니다.

인증 : AI 비서는 authenticate-gmail 도구를 사용하여 사용자의 Gmail 계정을 인증합니다.
이메일 관리 : 도우미는 서버가 제공하는 다양한 도구를 사용하여 이메일을 검색, 조사, 관리할 수 있습니다.
이메일 작성 : 보조 도구는 사용자 지시에 따라 이메일 초안을 작성하고 보내는 데 도움을 줄 수 있습니다.
이메일 정리 : 도우미는 라벨을 만들고, 라벨 간에 이메일을 이동하고, 이메일을 읽음/읽지 않음으로 표시하여 이메일을 정리하는 데 도움을 줄 수 있습니다.
이메일 요약 : 도우미는 summarize-emails 프롬프트를 사용하여 이메일을 요약할 수 있습니다.

AI 어시스턴트와 연결

클로드 데스크탑

Claude Desktop에 Gmail IMAP MCP 서버를 연결하려면:

Gmail IMAP MCP 서버를 시작합니다.
python -m gmail_imap_mcp.server
Claude Desktop을 열고 설정(기어 아이콘)으로 이동합니다.
"고급" 섹션으로 스크롤하여 "MCP 구성 편집"을 클릭하세요.
Gmail IMAP MCP 서버 구성을 추가합니다.
{ "servers": [ { "name": "Gmail IMAP", "url": "http://localhost:8080", "tools": [ "authenticate-gmail", "get-unread-emails", "get-email", "search-emails", "reply-to-message", "reply-to-thread", "send-email", "list-labels", "create-label", "delete-label", "move-email", "mark-as-read", "mark-as-unread", "download-attachment" ] } ] }
"저장"을 클릭하고 Claude Desktop을 다시 시작하세요.
이제 Claude에게 Gmail 계정과 상호 작용하도록 요청할 수 있습니다. 최상의 결과를 얻으려면 위의 "Claude 데스크톱 가이드" 섹션에서 답장 기능의 올바른 사용법과 이메일 처리 모범 사례를 참조하세요.시도해 볼 만한 추천 작업:
- "읽지 않은 이메일 보여줘"
- "[ID] 이메일의 전체 내용을 확인하세요"
- "[내용]을 포함하여 이 이메일에 답장하세요"
- "[내용]으로 이 이메일 스레드를 계속하세요"
- "이 이메일을 읽음으로 표시"
- "[발신자]의 이메일 검색"

중요 참고 사항: 이메일 답장의 경우, 적절한 이메일 스레드를 유지하려면 send-email 대신 반드시 적절한 답장 기능( reply-to-message 또는 reply-to-thread )을 사용하세요!

윈드서프 IDE

Gmail IMAP MCP 서버를 Windsurf IDE에 연결하려면:

Gmail IMAP MCP 서버를 시작합니다.
python -m gmail_imap_mcp.server
Windsurf IDE를 열고 설정으로 이동합니다.
"AI 흐름" 또는 "MCP 구성" 섹션을 찾으세요.
Gmail IMAP MCP 서버 구성을 추가합니다.
{ "servers": [ { "name": "Gmail IMAP", "url": "http://localhost:8080", "tools": [ "list-emails", "get-email", "search-emails", "send-email", "list-mailboxes", "create-label", "move-email", "mark-as-read", "download-attachment" ] } ] }
설정을 저장하고 필요한 경우 Windsurf를 다시 시작하세요.
이제 Claude Desktop과 동일한 명령을 사용하여 Cascade(Windsurf의 AI 도우미)가 Gmail 계정과 상호 작용하도록 요청할 수 있습니다.

일반적인 사용 사례

1. 이메일 분류

Assistant: I'll help you triage your unread emails.
User: Yes, please check my unread emails.
Assistant: [Uses get-unread-emails tool]
Assistant: You have 5 unread emails. The most urgent appears to be from your boss about the quarterly report due tomorrow.
User: Mark that as read and I'll look at it right away.
Assistant: [Uses mark-as-read tool]

2. 이메일 검색 및 구성

Assistant: Would you like me to find specific emails for you?
User: Yes, find all emails from john@example.com about the project budget.
Assistant: [Uses search-emails tool with query "from:john@example.com project budget"]
Assistant: I found 3 emails from John about the project budget. Would you like me to create a label for these?
User: Yes, create a "Budget" label and move them there.
Assistant: [Uses create-label tool followed by move-email tool for each email]

3. 이메일 작성

Assistant: Would you like me to draft an email for you?
User: Yes, write a follow-up email to the marketing team about our campaign results.
Assistant: [Drafts email content]
Assistant: Here's a draft. Would you like me to send it?
User: Yes, but add Sarah in CC.
Assistant: [Uses send-email tool with the drafted content and CC]

Gmail 관련 고려 사항

라벨 명명 규칙

Gmail에는 라벨 이름에 대한 특정 요구 사항이 있습니다.

레이블 이름은 대소문자를 구분합니다.
일부 특수 문자는 허용되지 않을 수 있습니다.
시스템 라벨(예: 받은 편지함, 보낸 편지함, 휴지통)을 생성하거나 삭제할 수 없습니다.
중첩된 레이블은 슬래시로 표시됩니다(예: "Projects/ProjectX").

이메일 ID 형식

이 MCP 서버에서 사용하는 이메일 ID 형식은 다음과 같습니다.

email://message/{account}_{mailbox}_{id}

이메일 ID가 필요한 도구(예: mark-as-read 또는 move-email )를 사용하는 경우 이메일 검색 도구에서 반환된 전체 리소스 URI를 사용해야 합니다.

보안 고려 사항

서버는 OAuth2 자격 증명을 ~/.gmail_imap_mcp_credentials 디렉토리에 로컬로 저장합니다.
client_secret.json 또는 토큰 파일을 공유하지 마십시오.
서버는 보안 연결을 사용하여 Gmail의 IMAP 서버에만 연결합니다.
이메일 첨부 파일은 기본적으로 downloads 디렉토리에 다운로드됩니다.
공유 환경에서 서버를 사용할 때는 이메일 데이터를 보호하기 위해 주의하세요.

문제 해결

인증 문제

client_secret.json 이 ~/.gmail_imap_mcp_credentials 디렉토리에 올바르게 배치되었는지 확인하세요.
Google Cloud 프로젝트에서 Gmail API를 활성화했는지 확인하세요.
토큰이 만료된 경우 다시 인증을 시도하세요.
"읽기 전용 파일 시스템" 오류가 표시되면 자격 증명 디렉터리가 쓰기 가능한지 확인하십시오.

연결 문제

인터넷 연결을 확인하세요
Google 계정에 IMAP 액세스를 차단할 수 있는 보안 제한이 없는지 확인하세요.
Google 계정 설정에서 "보안 수준이 낮은 앱 액세스"를 활성화해야 하는지 확인하세요.

이메일 전송 문제

Gmail 계정에서 SMTP 액세스를 허용하는지 확인하세요.
Google 계정 설정에서 "보안 수준이 낮은 앱 액세스"를 활성화해야 하는지 확인하세요.
첨부 파일이 너무 크지 않은지 확인하세요(Gmail의 경우 25MB 제한이 있습니다)

라벨 관리 문제

레이블 생성에 실패하면 레이블이 이미 있는지 확인하세요(대소문자 구분).
시스템 라벨을 생성하거나 삭제할 수 없습니다.
레이블 이름이 Gmail 명명 규칙을 따르는지 확인하세요.

이메일 이동 문제

레이블 간 이메일 이동이 실패하는 경우 소스 레이블과 대상 레이블이 모두 있는지 확인하십시오.
이메일 ID 형식이 올바른지 확인하세요
이메일을 수정할 수 있는 충분한 권한이 있는지 확인하세요.

이메일 ID 구문 분석 문제

이메일 ID에 대한 작업이 실패하면 전체 리소스 URI를 사용하고 있는지 확인하세요.
시스템은 URI의 마지막 부분을 실제 이메일 ID로 구문 분석합니다.
형식은 다음과 같아야 합니다: email://message/{account}_{mailbox}_{id}

특허

MIT 라이센스

지원하다

문제 및 기능 요청이 있으시면 GitHub 저장소에 문제를 열어주세요.

명령줄 인터페이스

이 패키지는 MCP 서버 외에도 Gmail 계정과 직접 상호 작용할 수 있는 명령줄 인터페이스(CLI)를 제공합니다.

설치

패키지를 설치하면 CLI가 자동으로 설치됩니다.

pip install -e .

사용 가능한 명령

1. Gmail 계정 인증

gmail-imap-cli authenticate your.email@gmail.com

2. 특정 메시지에 답장하기

gmail-imap-cli reply-to-message your.email@gmail.com 12345 "Thanks for your email." --mailbox INBOX --html "<p>Thanks for your email.</p>" --attachments /path/to/file1.pdf /path/to/file2.docx

3. 스레드에 답글 달기

gmail-imap-cli reply-to-thread your.email@gmail.com 12345 "Let's continue this discussion." --mailbox INBOX --html "<p>Let's continue this discussion.</p>" --attachments /path/to/file.pdf

CLI 인수

CLI는 메시지와 스레드에 답변하기 위해 다음 인수를 지원합니다.

account : 사용할 Gmail 계정
email_id / thread_id : 답장할 이메일/스레드 ID
body : 답장 메시지 본문(일반 텍스트)
--mailbox : 이메일/스레드가 포함된 사서함(기본값: INBOX)
--html : 답변 본문의 HTML 버전
--attachments : 답변에 첨부할 하나 이상의 파일 경로

Integrations

Gmail IMAP MCP 서버

특징

필수 조건

설치

소스에서 설치

Google Cloud 프로젝트 설정

최근 개선 사항

향상된 검색 기능

문의 양식 이메일 처리

백틱 JSON 처리

클로드 데스크톱 가이드

주요 도구 및 기능

1. 답변 기능(중요)

2. 이메일 콘텐츠 검색

클로드를 위한 모범 사례

특별한 경우

문의 양식 이메일

이메일 ID 및 리소스 URI

권장 워크플로

도구 참조

입증

이메일 검색

이메일 전송

라벨 관리

이메일 구성

고급 사용 예

날짜 범위 및 레이블을 사용한 향상된 검색

추가 필터링을 통해 읽지 않은 이메일 가져오기

복잡한 Gmail 쿼리로 검색

아키텍처 및 구현 세부 정보

자격 증명 저장소

IMAP 구현

이메일 ID 형식

기여하다

용법

서버 시작

Gmail 계정 인증

사용 가능한 도구 및 예

입증

1. 인증-gmail

이메일 검색 및 검색

2. 검색-이메일

3. 읽지 않은 이메일 가져오기

이메일 작성 및 발송

4. 이메일 보내기

5. 메시지에 대한 답장

6. 스레드에 대한 답변

라벨 관리

7. 라벨 생성

8. 레이블 삭제

9. 리스트-레이블

이메일 구성

10. 이동-이메일

첨부 파일 처리

11. 다운로드-첨부파일

이메일 상태 관리

12. 읽음으로 표시

13. 읽지 않음으로 표시

사용 가능한 프롬프트

1. 요약 이메일

AI 어시스턴트와의 통합

AI 어시스턴트와 연결

클로드 데스크탑

윈드서프 IDE

일반적인 사용 사례

1. 이메일 분류

2. 이메일 검색 및 구성

3. 이메일 작성

Gmail 관련 고려 사항

라벨 명명 규칙

이메일 ID 형식

보안 고려 사항

문제 해결

인증 문제

연결 문제

이메일 전송 문제

라벨 관리 문제

이메일 이동 문제

이메일 ID 구문 분석 문제