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 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

Integrations