Google 캘린더 MCP 서버

🔔 버전 업데이트 공지 🔔
버전 1.0.2에는 부분 업데이트 수행 시 기존 이벤트 데이터를 보존하는 updateEvent 함수에 대한 수정 사항이 포함되어 있습니다. 버전 1.0.1에는 Node.js v20.9.0 이상 버전과 'open' 패키지의 호환성을 위한 수정 사항이 포함되어 있으며, 해당 패키지는 버전 10 이상에서 ESM 전용입니다. 버전 1.0.0은 포괄적인 코드 리팩토링 및 국제화를 통해 정식 출시된 첫 번째 릴리스입니다.

프로젝트 개요

Google 캘린더 MCP 서버는 Google 캘린더와 Claude Desktop 간의 통합을 지원하는 MCP(Model Context Protocol) 서버 구현입니다. 이 프로젝트를 통해 Claude는 사용자의 Google 캘린더와 상호 작용하여 자연어 상호 작용을 통해 캘린더 일정을 표시, 생성, 업데이트 및 삭제할 수 있습니다.

핵심 기능

• Google 캘린더 통합 : Claude Desktop과 Google 캘린더 API 간의 브리지를 제공합니다.
• MCP 구현 : AI 어시스턴트 도구 통합을 위한 모델 컨텍스트 프로토콜 사양을 따릅니다.
• OAuth2 인증 : Google API 인증 흐름을 안전하게 처리합니다.
• 이벤트 관리 : 포괄적인 캘린더 이벤트 작업(가져오기, 만들기, 업데이트, 삭제)을 지원합니다.
• 색상 지원 : colorId 매개변수를 사용하여 이벤트 색상을 설정하고 업데이트하는 기능
• STDIO 전송 : Claude Desktop과의 통신을 위해 표준 입력/출력을 사용합니다.

기술 아키텍처

이 프로젝트에서는 다음을 사용합니다.

• TypeScript : 유형 안전한 코드 개발을 위해
• MCP SDK : Claude Desktop과 통합하기 위해 @modelcontextprotocol/sdk 사용합니다.
• Google API : Google 캘린더 API 액세스를 위해 googleapis 사용합니다.
• Zod : 요청/응답 데이터에 대한 스키마 검증을 구현합니다.
• 환경 기반 구성 : 구성 관리를 위해 dotenv를 사용합니다.
• Helmet.js : 보안 헤더용
• AES-256-GCM : 토큰 암호화용
• Jest : 단위 테스트 및 커버리지용
• GitHub Actions : CI/CD용

주요 구성 요소

1. MCP 서버 : Claude Desktop과의 통신을 처리하는 핵심 서버 구현
2. Google 캘린더 도구 : 캘린더 작업(검색, 생성, 업데이트, 삭제)
3. 인증 핸들러 : Google API를 사용한 OAuth2 흐름 관리
4. 스키마 검증 : 모든 작업에서 데이터 무결성 보장
5. 토큰 관리자 : 인증 토큰의 안전한 처리

사용 가능한 도구

이 MCP 서버는 Google 캘린더와 상호 작용하기 위한 다음과 같은 도구를 제공합니다.

1. 이벤트 가져오기

다양한 필터링 옵션을 사용하여 캘린더 이벤트를 검색합니다.

매개변수:

• calendarId (선택 사항): 캘린더 ID(생략 시 기본 캘린더 사용)
• timeMin (선택 사항): 이벤트 검색 시작 시간(ISO 8601 형식, 예: "2025-03-01T00:00:00Z")
• timeMax (선택 사항): 이벤트 검색 종료 시간(ISO 8601 형식)
• maxResults (선택 사항): 검색할 최대 이벤트 수(기본값: 10)
• orderBy (선택 사항): 정렬 순서("startTime" 또는 "updated")

2. 이벤트 생성

새로운 캘린더 이벤트를 만듭니다.

매개변수:

• calendarId (선택 사항): 캘린더 ID(생략 시 기본 캘린더 사용)
• event : 이벤트 세부 정보 객체에는 다음이 포함됩니다.
  • summary (필수): 이벤트 제목
  • description (선택 사항): 이벤트 설명
  • location (선택 사항): 이벤트 위치
  • start : 시작 시간 객체:
    • dateTime (선택 사항): ISO 8601 형식(예: "2025-03-15T09:00:00+09:00")
    • date (선택 사항): 종일 이벤트의 경우 YYYY-MM-DD 형식
    • timeZone (선택 사항): 시간대(예: "Asia/Tokyo")
  • end : 종료 시간 객체(start와 동일한 형식)
  • attendees (선택 사항): 이메일과 선택 사항인 displayName이 있는 참석자 배열
  • colorId (선택 사항): 이벤트 색상 ID(1-11)

3. 업데이트 이벤트

기존 캘린더 이벤트를 업데이트합니다. 이 함수는 기존 이벤트 데이터를 먼저 가져와 업데이트 데이터와 병합하며, 업데이트 요청에 포함되지 않은 필드는 그대로 유지합니다.

매개변수:

• calendarId (선택 사항): 캘린더 ID(생략 시 기본 캘린더 사용)
• eventId (필수): 업데이트할 이벤트의 ID
• event : 업데이트할 필드가 포함된 이벤트 세부 정보 객체(createEvent와 동일한 구조, 모든 필드는 선택 사항)
  • 명시적으로 제공된 필드만 업데이트됩니다.
  • 업데이트 요청에 포함되지 않은 필드는 기존 값을 유지합니다.
  • 이를 통해 데이터 손실 없이 부분 업데이트가 가능합니다.

4. 이벤트 삭제

캘린더 이벤트를 삭제합니다.

매개변수:

• calendarId (선택 사항): 캘린더 ID(생략 시 기본 캘린더 사용)
• eventId (필수): 삭제할 이벤트의 ID

개발 지침

새로운 기능을 추가하거나, 코드를 수정하거나, 버그를 수정할 때는 npm version 명령을 사용하여 각 변경 사항의 버전을 의미적으로 높여주세요. 또한, 코딩이 명확하고 객체 지향 프로그래밍(OOP)과 같은 모든 필수 코딩 규칙을 준수하는지 확인하세요. 버전이 업데이트되면 버전 스크립트가 자동으로 npm install 실행하지만, 제출하기 전에 코드를 빌드하고, lint를 실행하고, 테스트해야 합니다.

코드 구조

• src/ : 소스 코드 디렉토리
  • auth/ : 인증 처리
  • config/ : 구성 설정
  • mcp/ : MCP 서버 구현
  • tools/ : Google 캘린더 도구 구현
  • utils/ : 유틸리티 함수 및 도우미

모범 사례

• TypeScript 모범 사례에 따른 적절한 타이핑
• 포괄적인 오류 처리 유지
• 적절한 인증 흐름을 보장하세요
• 종속성을 최신 상태로 유지하세요
• 모든 기능에 대한 명확한 문서를 작성하세요
• 보안 모범 사례 구현
• OAuth 2.1 인증 표준을 따르세요
• 모든 입력/출력 데이터에 스키마 검증을 사용합니다.

테스트

• 핵심 기능에 대한 단위 테스트 구현
• 인증 흐름을 철저히 테스트하세요
• Google API에 대한 캘린더 조작 확인
• 커버리지 보고서로 테스트 실행
• 보안 테스트가 포함되어 있는지 확인하세요

전개

이 패키지는 npm에 @takumi0706/google-calendar-mcp 로 게시되었습니다.

지엑스피1

필수 조건

1. Google Cloud 프로젝트를 만들고 Google 캘린더 API를 활성화하세요.
2. Google Cloud Console에서 OAuth2 자격 증명 구성
3. 환경 변수 설정:

클로드 데스크톱 구성

claude_desktop_config.json 에 서버를 추가합니다.

보안 고려 사항

• OAuth 토큰은 메모리에만 저장됩니다(파일 기반 저장소에는 저장되지 않음)
• 민감한 자격 증명은 환경 변수로 제공되어야 합니다.
• 안전한 저장을 위한 AES-256-GCM을 사용한 토큰 암호화
• 명시적 code_verifier 및 code_challenge 생성을 통한 PKCE 구현
• CSRF 보호를 위한 상태 매개변수 검증
• Helmet.js를 사용하여 적용된 보안 헤더
• API 엔드포인트 보호를 위한 속도 제한
• Zod 스키마를 사용한 입력 검증

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

유지

• Google 캘린더 API와의 호환성을 유지하기 위한 정기 업데이트
• 버전 업데이트는 README.md에 기록되어 있습니다.
• 로그는 사용자의 홈 디렉토리 ~/.google-calendar-mcp/logs/ 에 저장됩니다.

문제 해결

문제가 발생할 경우:

1. ~/.google-calendar-mcp/logs/ 의 홈 디렉토리에서 로그를 확인하세요.
2. Google OAuth 자격 증명이 올바르게 구성되었는지 확인하세요.
3. Google 캘린더 API 액세스에 대한 충분한 권한이 있는지 확인하세요.
4. Claude Desktop 구성이 올바른지 확인하세요

일반적인 오류

• JSON 구문 분석 오류 : Unexpected non-whitespace character after JSON at position 4 (line 1 column 5) 와 같은 오류가 발생하는 경우, 일반적으로 JSON-RPC 메시지 형식이 잘못되었기 때문입니다. 이 문제는 0.6.7 버전 이상에서 해결되었습니다. 이러한 오류가 계속 발생하는 경우 최신 버전으로 업데이트하세요.
• 인증 오류 : Google OAuth 자격 증명을 확인하세요
• 연결 오류 : 서버의 인스턴스가 하나만 실행되고 있는지 확인하세요.
• 연결 해제 문제 : 사용자 정의 TCP 소켓 없이 서버가 MCP 메시지를 제대로 처리하는지 확인하세요.

버전 기록

버전 1.0.2 변경 사항

• 부분 업데이트 수행 시 기존 이벤트 데이터를 보존하기 위해 updateEvent 함수를 수정했습니다.
• 업데이트하기 전에 기존 이벤트 데이터를 가져오기 위해 getEvent 함수가 추가되었습니다.
• 데이터 손실을 방지하기 위해 업데이트 데이터를 기존 데이터와 병합하도록 updateEvent 수정했습니다.
• 업데이트 요청에서 모든 필드를 선택 사항으로 만들기 위해 스키마 유효성 검사를 업데이트했습니다.
• updateEvent 함수에 대한 문서가 개선되었습니다.

버전 1.0.1 변경 사항

• Node.js v20.9.0+ 및 'open' 패키지(v10+)와의 호환성 문제가 해결되었습니다.
• ESM 전용 '열림' 패키지에 대한 정적 가져오기를 동적 가져오기로 교체했습니다.
• OAuth 인증 중 브라우저 열기 오류 처리가 개선되었습니다.
• 더 나은 유지 관리를 위한 향상된 코드 주석

버전 1.0.0 변경 사항

• 주요 버전 출시로 생산 준비 완료
• 향상된 유지 관리를 위한 포괄적인 코드 리팩토링
• 모든 메시지와 댓글의 국제화(일본어에서 영어로 번역)
• 향상된 코드 일관성 및 가독성
• 더 나은 사용자 경험을 위해 오류 메시지가 개선되었습니다.
• 프로젝트의 현재 상태를 반영하기 위해 업데이트된 문서
• 코드베이스 전체에 걸쳐 표준화된 코딩 스타일

버전 0.8.0 변경 사항

• 새로 고침 토큰 문제를 처리하기 위한 향상된 OAuth 인증 흐름
• Google에서 동의 화면을 표시하고 새 새로 고침 토큰을 제공하도록 강제하는 prompt: 'consent'
• 새로 고침 토큰을 사용할 수 없는 경우 액세스 토큰만으로 작동하도록 수정된 인증 흐름
• 새로 고침 토큰이 없거나 새로 고침 토큰이 유효하지 않은 경우를 처리하기 위해 토큰 새로 고침 논리가 개선되었습니다.
• 더 나은 토큰 관리를 위해 새로 고침된 액세스 토큰을 저장하기 위해 토큰 저장소를 업데이트했습니다.
• 토큰 새로 고침 논리에서 잠재적 무한 루프가 수정되었습니다.

개발

이 프로젝트에 기여하려면:

테스트

테스트를 실행하려면:

특허

MIT