Google 캘린더 MCP 서버

Google 캘린더와의 통합을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. LLM은 표준화된 인터페이스를 통해 캘린더 일정을 읽고, 만들고, 관리할 수 있습니다.

특징

• 사용 가능한 캘린더 나열
• 캘린더에서 이벤트 나열
• 새 캘린더 이벤트 만들기
• 기존 이벤트 업데이트
• 이벤트 삭제
• 스크린샷 및 이미지에서 이벤트 처리

요구 사항

1. Node.js 16 이상
2. TypeScript 5.3 이상
3. 캘린더 API가 활성화된 Google Cloud 프로젝트
4. OAuth 2.0 자격 증명(클라이언트 ID 및 클라이언트 비밀번호)

프로젝트 구조

지엑스피1

Google 클라우드 설정

1. Google Cloud Console 로 이동
2. 새로운 프로젝트를 만들거나 기존 프로젝트를 선택하세요.
3. 프로젝트에 Google 캘린더 API를 활성화하세요. API를 활성화하기 전에 상단 표시줄에서 올바른 프로젝트를 선택했는지 확인하세요.
4. OAuth 2.0 자격 증명을 만듭니다.
   • 자격 증명으로 이동
   • "자격 증명 만들기" > "OAuth 클라이언트 ID"를 클릭하세요.
   • 앱이 액세스할 데이터 유형에 대해 "사용자 데이터"를 선택하세요.
   • 앱 이름과 연락처 정보를 추가하세요
   • 다음 범위를 추가합니다(선택 사항):
     • https://www.googleapis.com/auth/calendar.events
   • 애플리케이션 유형으로 "데스크톱 앱"을 선택하세요
   • OAuth 동의 화면 에서 테스트 사용자로 이메일 주소를 추가하세요.
     • 참고: 테스트 사용자를 추가하는 데 몇 분 정도 소요됩니다. OAuth 동의는 테스트 사용자가 전파될 때까지 진행할 수 없습니다.

설치

1. 저장소를 복제합니다
2. 종속성 설치:
   npm install
3. TypeScript 코드를 작성합니다.
   npm run build
4. Google Cloud Console에서 Google OAuth 자격 증명을 다운로드하고("자격 증명" 아래), 파일 이름을 gcp-oauth.keys.json 으로 바꾸고 프로젝트의 루트 디렉토리에 넣습니다.

사용 가능한 스크립트

• npm run build - TypeScript 코드 빌드
• npm run build:watch - 개발을 위한 감시 모드에서 TypeScript 빌드
• npm run dev - ts-node를 사용하여 개발 모드로 서버를 시작합니다.
• npm run auth - Google OAuth 흐름에 대한 인증 서버 시작

입증

서버는 자동 및 수동 인증 흐름을 모두 지원합니다.

자동 인증(권장)

1. 프로젝트의 루트 디렉토리에 있는 gcp-oauth.keys.json 이라는 파일에 Google OAuth 자격 증명을 저장합니다.
2. MCP 서버를 시작합니다.
   npm start
3. 유효한 인증 토큰을 찾을 수 없는 경우 서버는 자동으로 다음을 수행합니다.
   • 인증 서버 시작(포트 3000-3004)
   • OAuth 흐름에 대한 브라우저 창을 엽니다.
   • 인증 후 토큰을 안전하게 저장하세요
   • 인증 서버를 종료합니다
   • 정상적인 MCP 서버 작업을 계속합니다.

서버는 필요할 때 토큰 새로 고침 및 재인증을 자동으로 관리합니다.

• 토큰은 만료 전에 자동으로 새로 고쳐집니다.
• 새로 고침이 실패하면 오류 메시지가 지워지고 재인증을 안내합니다.
• 토큰 파일은 제한된 권한으로 안전하게 저장됩니다.

수동 인증

고급 사용자 또는 문제 해결을 위해 인증 흐름을 수동으로 실행할 수 있습니다.

이렇게 하면:

1. 인증 서버를 시작합니다
2. OAuth 흐름에 대한 브라우저 창을 엽니다.
3. 토큰을 저장하고 종료합니다.

보안 참고 사항

• OAuth 자격 증명은 gcp-oauth.keys.json 에 저장됩니다.
• 인증 토큰은 600개의 권한으로 .gcp-saved-tokens.json 에 저장됩니다.
• 토큰은 백그라운드에서 자동으로 새로 고쳐집니다.
• 각 API 호출 전에 토큰 무결성이 검증됩니다.
• 인증이 성공적으로 완료되면 인증 서버가 자동으로 종료됩니다.
• OAuth 자격 증명이나 토큰 파일을 버전 제어에 커밋하지 마십시오.

용법

서버는 다음 도구를 제공합니다.

• list-calendars : 사용 가능한 모든 캘린더를 나열합니다.
• list-events : 캘린더에서 이벤트 나열
• create-event : 새로운 캘린더 이벤트를 만듭니다
• update-event : 기존 캘린더 이벤트를 업데이트합니다.
• delete-event : 캘린더 이벤트 삭제

Claude Desktop과 함께 사용

1. Claude Desktop 구성 파일에 다음 구성을 추가하세요. 예: /Users/<user>/Library/Application Support/Claude/claude_desktop_config.json
   { "mcpServers": { "google-calendar": { "command": "node", "args": ["path/to/build/index.js"] } } }
2. Claude Desktop을 다시 시작하세요

사용 예

캘린더 통합에서 기대하는 일반적인 기능 외에도 스크린샷과 이미지에서 이벤트를 추가하는 등 매우 동적인 작업도 수행할 수 있습니다.

1. 스크린샷과 이미지에서 이벤트 추가:
   Add this event to my calendar based on the attached screenshot.
   지원되는 이미지 형식: PNG, JPEG, GIF 이미지에는 날짜, 시간, 위치, 설명과 같은 이벤트 세부 정보가 포함될 수 있습니다.
2. 참석 확인:
   Which events tomorrow have attendees who have not accepted the invitation?
3. 자동 조정 이벤트:
   Here's some available that was provided to me by someone I am interviewing. Take a look at the available times and create an event for me to interview them that is free on my work calendar.
4. 귀하의 이용 가능 시간을 직접 입력하세요:
   Please provide availability looking at both my personal and work calendar for this upcoming week. Choose times that work well for normal working hours on the East Coast. Meeting time is 1 hour

개발

문제 해결

일반적인 문제 및 해결 방법:

1. OAuth 토큰은 1주일(7일) 후에 만료됩니다.
   • 프로덕션 모드가 아닌 테스트 모드에 있는 앱은 일주일 후에 다시 OAuth 흐름을 거쳐야 합니다.
2. OAuth 토큰 오류
   • gcp-oauth.keys.json 이 올바른 형식인지 확인하세요.
   • .gcp-saved-tokens.json 삭제하고 다시 인증해보세요.
3. TypeScript 빌드 오류
   • 모든 종속성이 설치되었는지 확인하세요: npm install
   • Node.js 버전이 필수 구성 요소와 일치하는지 확인하세요.
   • 빌드 디렉토리를 지웁니다: rm -rf build/
4. 이미지 처리 문제
   • 이미지 형식이 지원되는지 확인하세요
   • 이미지에 명확하고 읽기 쉬운 텍스트가 포함되어 있는지 확인하세요.

보안 참고 사항

• 서버는 로컬로 실행되며 OAuth 인증이 필요합니다.
• OAuth 자격 증명은 프로젝트 루트의 gcp-oauth.keys.json 에 저장되어야 합니다.
• 인증 토큰은 제한된 파일 권한으로 .gcp-saved-tokens.json 에 저장됩니다.
• 토큰은 만료되면 자동으로 새로 고쳐집니다.
• OAuth 자격 증명이나 토큰 파일을 버전 제어에 커밋하지 마십시오.
• 프로덕션 용도로 사용하려면 Google에서 OAuth 애플리케이션을 검증받으세요.

특허

MIT