Gmail MCP 서버

Gmail API 통합을 위한 MCP(Model Context Protocol) 서버 구현으로 AI 어시스턴트가 Gmail 서비스와 상호 작용할 수 있습니다.

특징

핵심 기능

이메일 운영
- 고급 필터링으로 이메일 나열
- 전체 내용이 포함된 특정 이메일을 읽어보세요
- 새로운 이메일을 만들고 보내세요
초안 관리
- 새로운 초안 만들기
- 기존 초안 나열
- 초안 내용 읽기
- 초안 내용 및 수신자 업데이트
- 초안 삭제
캘린더 작업
- 예정된 캘린더 이벤트 나열
- 자세한 이벤트 정보를 읽어보세요
- 새 캘린더 이벤트 만들기
- 이벤트 필터링 및 검색
- 시간대 지원
- iOS 캘린더 동기화 지원

검색 및 필터링

Gmail 검색어 지원
레이블 기반 필터링
사용자 정의 가능한 결과 제한
캘린더 이벤트 검색 기능

보안

Google OAuth2.0 통합
보안 자격 증명 관리
토큰 처리 새로 고침
다중 범위 권한 지원

Related MCP server: Enhanced Gmail MCP Server

빠른 시작

필수 조건

Node.js(v14 이상)
npm(v6 이상)
Gmail 및 캘린더 API가 활성화된 Google Cloud Platform 계정
적절한 범위를 갖춘 OAuth 2.0 자격 증명

설치

종속성을 복제하고 설치합니다.
지엑스피1
환경 구성:
# Create .env file cp .env.example .env # Add your credentials: GOOGLE_CLIENT_ID="your_client_id" GOOGLE_CLIENT_SECRET="your_client_secret" REDIRECT_URI="http://localhost:4100/code" GOOGLE_REFRESH_TOKEN="your_refresh_token"
빌드하고 실행:
npm run build npm start

개발

사용 가능한 스크립트

npm run dev - watch 모드로 빌드하고 실행
npm run build - 프로젝트 빌드
npm run clean - 빌드 아티팩트 정리
npm run watch - 변경 사항 확인

프로젝트 구조

gmail-mcp-server/ ├── src/ │ ├── config/ # Configuration and setup │ ├── services/ # Core business logic │ │ ├── gmail/ # Gmail services │ │ └── calendar/ # Calendar services │ ├── tools/ # MCP tool implementations │ │ ├── calendar/ # Calendar tools │ │ ├── drafts/ # Draft management tools │ │ └── messages/ # Email tools │ ├── types/ # TypeScript definitions │ └── index.ts # Server entry point ├── dist/ # Compiled JavaScript └── tests/ # Test files (pending)

API 인터페이스

메시지 목록

listEmails({ maxResults?: number, // Default: 10 query?: string, // Gmail search query labelIds?: string[], // Filter by labels verbose?: boolean // Include details })

메시지 읽기

readEmail({ messageId: string // Message ID to fetch })

초안 작업

// List Drafts listDrafts({ maxResults?: number, // Default: 10 query?: string, // Search query verbose?: boolean // Include details }) // Read Draft readDraft({ draftId: string // Draft ID to fetch }) // Create Draft draftEmail({ to: string[], subject: string, body: string, cc?: string[], bcc?: string[], isHtml?: boolean }) // Update Draft updateDraft({ draftId: string, // Draft ID to update to?: string[], // New recipients cc?: string[], // New CC recipients bcc?: string[], // New BCC recipients subject?: string, // New subject body?: string, // New body content isHtml?: boolean // Content type flag }) // Delete Draft deleteDraft({ draftId: string // Draft ID to delete })

이메일 보내기

sendEmail({ to: string[], subject: string, body: string, cc?: string[], bcc?: string[], isHtml?: boolean, draftId?: string // Optional: send existing draft })

캘린더 작업

// List Events listEvents({ maxResults?: number, // Default: 25 timeMin?: string, // Start time (ISO 8601) timeMax?: string, // End time (ISO 8601) query?: string, // Text search term timeZone?: string // Default: Australia/Brisbane }) // Read Event Details readEvent({ eventId: string, // Event ID to fetch details timeZone?: string // Default: Australia/Brisbane }) // Create Event createEvent({ summary: string, // Event title start: { dateTime: string, // ISO 8601 start time timeZone?: string // Start time timezone }, end: { dateTime: string, // ISO 8601 end time timeZone?: string // End time timezone }, description?: string, // Optional event description location?: string, // Optional event location attendees?: Array<{ // Optional attendees email: string, displayName?: string, optional?: boolean }>, status?: 'confirmed' | 'tentative' | 'cancelled', sendNotifications?: boolean })

오류 처리

서버는 다음에 대한 포괄적인 오류 처리를 구현합니다.

인증 실패
API 속도 제한
잘못된 요청
네트워크 문제
캘린더 동기화 문제
이벤트 ID 검증
시간대 검증

기여하다

자세한 내용은 CONTRIBUTING.md를 참조하세요.

변경 사항

버전 기록과 업데이트는 CHANGELOG.md에서 확인하세요.

로드맵

계획된 기능과 개선 사항은 Backlog.md를 참조하세요.

특허

MIT 라이센스 - 자세한 내용은 라이센스를 참조하세요.

Gmail MCP Server