Gmail MCP 서버 - Claude Desktop에서 Gmail을 직접 관리
npm install @palinyee/gmail-mcp-serverClaude Desktop에서 Gmail을 직접 관리할 수 있게 해주는 Model Context Protocol (MCP) 서버입니다. 액세스 토큰을 사용한 간단한 인증으로 AI 어시스턴트가 Gmail을 자연어로 제어할 수 있습니다.
이 서버를 사용하려면 적절한 권한을 가진 Gmail 액세스 토큰이 필요합니다:
#### 방법 1: Google OAuth Playground (테스트용 - 가장 쉬움)
1. Google OAuth 2.0 Playground 접속
2. Step 1에서 다음 스코프 선택:
- https://www.googleapis.com/auth/gmail.modify
- https://www.googleapis.com/auth/gmail.settings.basic
3. "Authorize APIs" 클릭 후 Google 계정으로 로그인
4. Step 2에서 "Exchange authorization code for tokens" 클릭
5. 응답에서 "Access token" 복사
#### 방법 2: Google Cloud Console (프로덕션용)
1. Google Cloud Console에서 프로젝트 생성
2. Gmail API 활성화
3. OAuth 2.0 자격 증명 생성
4. 원하는 OAuth 플로우를 사용하여 필요한 스코프로 액세스 토큰 획득
액세스 토큰은 두 가지 방법으로 제공할 수 있습니다:
#### 옵션 1: 명령줄 인수
``bash`
npx @palinYEE/gmail-mcp-server YOUR_ACCESS_TOKEN_HERE
#### 옵션 2: 환경 변수
`bash`
export GMAIL_ACCESS_TOKEN=YOUR_ACCESS_TOKEN_HERE
npx @palinYEE/gmail-mcp-server
claude_desktop_config.json 파일에 다음과 같이 설정:
`json`
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@palinYEE/gmail-mcp-server",
"YOUR_ACCESS_TOKEN_HERE"
]
}
}
}
또는 환경 변수 사용:
`json`
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@palinYEE/gmail-mcp-server"
],
"env": {
"GMAIL_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
새 이메일을 즉시 전송합니다. 파일 첨부 지원.
기본 이메일:
`json`
{
"to": ["recipient@example.com"],
"subject": "내일 회의",
"body": "안녕하세요,\n\n내일 오전 10시 회의 잊지 마세요.\n\n감사합니다",
"cc": ["cc@example.com"],
"bcc": ["bcc@example.com"],
"mimeType": "text/plain"
}
파일 첨부 이메일:
`json`
{
"to": ["recipient@example.com"],
"subject": "프로젝트 파일",
"body": "안녕하세요,\n\n프로젝트 파일을 첨부합니다.\n\n감사합니다",
"attachments": [
"/path/to/document.pdf",
"/path/to/spreadsheet.xlsx"
]
}
HTML 이메일: 내일 회의 오전 10시입니다.
`json`
{
"to": ["recipient@example.com"],
"subject": "내일 회의",
"mimeType": "text/html",
"body": "회의 알림
}
`json`
{
"to": ["recipient@example.com"],
"subject": "보고서 초안",
"body": "검토를 위한 보고서 초안입니다.",
"attachments": ["/path/to/draft_report.docx"]
}
`json`
{
"messageId": "182ab45cd67ef"
}
응답 예시:
`
제목: 프로젝트 파일
발신: sender@example.com
수신: recipient@example.com
날짜: Thu, 19 Jun 2025 10:30:00 -0400
이메일 본문...
첨부 파일 (2):
- document.pdf (application/pdf, 245 KB, ID: ANGjdJ9fkTs-i3GCQo5o97f_itG...)
- spreadsheet.xlsx (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, 89 KB, ID: BWHkeL8gkUt...)
`
`json`
{
"messageId": "182ab45cd67ef",
"attachmentId": "ANGjdJ9fkTs-i3GCQo5o97f_itG...",
"savePath": "/path/to/downloads",
"filename": "downloaded_document.pdf"
}
매개변수:
- messageId: 첨부 파일이 있는 이메일 IDattachmentId
- : 첨부 파일 ID (이메일 읽기에서 확인 가능)savePath
- : 저장할 디렉토리 (선택사항, 기본값: 현재 디렉토리)filename
- : 사용자 정의 파일명 (선택사항, 기본값: 원본 파일명)
`json`
{
"query": "from:sender@example.com after:2024/01/01 has:attachment",
"maxResults": 10
}
`json`
{
"messageId": "182ab45cd67ef",
"addLabelIds": ["IMPORTANT"],
"removeLabelIds": ["INBOX"]
}
`json`
{
"messageId": "182ab45cd67ef"
}
`json`
{}
`json`
{
"name": "중요 프로젝트",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
`json`
{
"id": "Label_1234567890",
"name": "긴급 프로젝트",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
`json`
{
"id": "Label_1234567890"
}
`json`
{
"name": "프로젝트 XYZ",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
`json`
{
"messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
"addLabelIds": ["IMPORTANT"],
"removeLabelIds": ["INBOX"],
"batchSize": 50
}
`json`
{
"messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
"batchSize": 50
}
`json`
{
"criteria": {
"from": "newsletter@company.com",
"hasAttachment": false
},
"action": {
"addLabelIds": ["Label_Newsletter"],
"removeLabelIds": ["INBOX"]
}
}
사용 가능한 템플릿:
- fromSender: 특정 발신자 필터링withSubject
- : 제목 텍스트 필터링withAttachments
- : 첨부 파일 있는 이메일largeEmails
- : 대용량 이메일containingText
- : 특정 텍스트 포함mailingList
- : 메일링 리스트
예시:
`json`
{
"template": "fromSender",
"parameters": {
"senderEmail": "notifications@github.com",
"labelIds": ["Label_GitHub"],
"archive": true
}
}
search_emails 도구는 Gmail의 강력한 검색 연산자를 지원합니다:
| 연산자 | 예시 | 설명 |
|--------|------|------|
| from: | from:john@example.com | 특정 발신자 |to:
| | to:mary@example.com | 특정 수신자 |subject:
| | subject:"회의 노트" | 제목에 특정 텍스트 |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 타입과 파일 크기 자동 감지
- 다운로드: 모든 이메일 첨부 파일을 로컬에 저장
- 상세 정보: 파일명, 타입, 크기, 다운로드 ID 표시
- 다양한 형식: PDF, DOCX, XLSX, PPTX, 이미지, 압축 파일 등 모든 파일 형식 지원$3
- 한글, 중국어, 일본어, 아랍어 등 모든 언어 지원
- 특수 문자 및 기호 지원
- 올바른 인코딩으로 모든 이메일 클라이언트에서 정상 표시$3
- messageListVisibility: 메시지 목록에서 라벨 표시 (show 또는 hide)
- labelListVisibility: 라벨 목록에서 표시 방법 (labelShow, labelShowIfUnread, labelHide)$3
- 한 번에 최대 50개 이메일 처리 (설정 가능)
- API 제한 회피를 위한 자동 청킹
- 각 작업의 성공/실패 상세 보고
- 개별 재시도를 통한 우아한 오류 처리보안 주의사항
- 액세스 토큰을 절대 버전 관리 시스템에 커밋하지 마세요
- 액세스 토큰은 주기적으로 만료됩니다 - 만료 시 새로 발급받아야 합니다
- 사용 사례에 필요한 최소한의 권한만 부여하세요
- Google 계정 설정에서 사용하지 않는 토큰을 정기적으로 검토하고 취소하세요
- 첨부 파일은 로컬에서 처리되며 서버에 영구 저장되지 않습니다
문제 해결
$3
- 명령줄 인수 또는 환경 변수로 액세스 토큰을 제공했는지 확인
- 토큰 형식이 올바른지 확인 (추가 공백이나 따옴표 제거)$3
- 액세스 토큰이 만료되었을 수 있음 - 새로 발급
- 토큰에 필요한 Gmail 스코프가 있는지 확인
- 올바른 Google 계정을 사용하는지 확인$3
- Google Cloud 프로젝트에서 Gmail API가 활성화되어 있는지 확인
- 토큰에 필요한 스코프(gmail.modify 및 gmail.settings.basic)가 있는지 확인$3
- 배치 작업이 실패하면 자동으로 개별 항목 재시도
- 특정 실패에 대한 상세 오류 메시지 확인
- 속도 제한에 걸리면 배치 크기 줄이기 고려$3
- 파일 찾을 수 없음: 첨부 파일 경로가 올바르고 접근 가능한지 확인
- 권한 오류: 서버가 첨부 파일에 대한 읽기 권한이 있는지 확인
- 크기 제한: Gmail은 이메일당 25MB 첨부 파일 크기 제한
- 다운로드 실패: 다운로드 디렉토리에 쓰기 권한이 있는지 확인개발 및 테스트
$3
MCP 평가를 실행하여 서버 기능을 테스트할 수 있습니다:
`bash
OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/index.ts
``평가 패키지는 index.ts 파일을 실행하는 MCP 클라이언트를 로드하므로 테스트 간에 재빌드가 필요하지 않습니다.
기여를 환영합니다! Pull Request를 자유롭게 제출해 주세요.
MIT
문제가 발생하거나 질문이 있으면 GitHub 저장소에 이슈를 등록해 주세요.