Gmail MCP 서버
Gmail API 통합을 위한 MCP(Model Context Protocol) 서버 구현으로 AI 어시스턴트가 Gmail 서비스와 상호 작용할 수 있습니다.
특징
핵심 기능
- 이메일 운영
- 고급 필터링으로 이메일 나열
- 전체 내용이 포함된 특정 이메일을 읽어보세요
- 새로운 이메일을 만들고 보내세요
- 초안 관리
- 새로운 초안 만들기
- 기존 초안 나열
- 초안 내용 읽기
- 초안 내용 및 수신자 업데이트
- 초안 삭제
- 캘린더 작업
- 예정된 캘린더 이벤트 나열
- 자세한 이벤트 정보를 읽어보세요
- 새 캘린더 이벤트 만들기
- 이벤트 필터링 및 검색
- 시간대 지원
- iOS 캘린더 동기화 지원
검색 및 필터링
- Gmail 검색어 지원
- 레이블 기반 필터링
- 사용자 정의 가능한 결과 제한
- 캘린더 이벤트 검색 기능
보안
- Google OAuth2.0 통합
- 보안 자격 증명 관리
- 토큰 처리 새로 고침
- 다중 범위 권한 지원
빠른 시작
필수 조건
- 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 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 라이센스 - 자세한 내용은 라이센스를 참조하세요.