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 프로젝트 만들기:
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
# 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이 이미 사용 중이면 인증을 실행하기 전에 포트를 비워주세요.
- 해당 포트를 사용하여 프로세스를 찾아 중지할 수 있습니다.
- 배치 작업 실패
- 일괄 작업이 실패하면 개별 항목을 자동으로 다시 시도합니다.
- 특정 실패에 대한 자세한 오류 메시지를 확인하세요.
- 속도 제한이 발생하는 경우 배치 크기를 줄이는 것을 고려하세요.
기여하다
기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.
실행 평가
evals 패키지는 index.ts 파일을 실행하는 mcp 클라이언트를 로드하므로 테스트 사이에 다시 빌드할 필요가 없습니다. npx 명령 앞에 접두사를 붙여 환경 변수를 로드할 수 있습니다. 전체 문서는 여기에서 확인할 수 있습니다.
OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/index.ts
특허
MIT
지원하다
문제가 발생하거나 질문이 있는 경우 GitHub 저장소에 문제를 제출하세요.