Google 캘린더 MCP 서버

Google 캘린더와의 통합을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. LLM은 표준화된 인터페이스를 통해 캘린더 이벤트를 읽고, 생성하고, 업데이트하고, 검색할 수 있습니다.

사용 예

캘린더 통합에 기대하는 일반적인 기능 외에도 다음과 같이 매우 동적인 여러 단계로 구성된 프로세스도 수행할 수 있습니다.

스크린샷과 이미지에서 이벤트 추가:지엑스피1지원되는 이미지 형식: PNG, JPEG, GIF 이미지에는 날짜, 시간, 위치, 설명과 같은 이벤트 세부 정보가 포함될 수 있습니다.
달력 분석:
What events do I have coming up this week that aren't part of my usual routine?
참석 확인:
Which events tomorrow have attendees who have not accepted the invitation?
자동 조정 이벤트:
Here's some available that was provided to me by someone. Take a look at the available times and create an event that is free on my work calendar.
귀하의 이용 가능 시간을 직접 입력하세요:
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

요구 사항

Node.js(최신 LTS 권장)
TypeScript 5.3 이상
캘린더 API가 활성화된 Google Cloud 프로젝트
OAuth 2.0 자격 증명(클라이언트 ID 및 클라이언트 비밀번호)

Google 클라우드 설정

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

설치

저장소를 복제합니다
종속성을 설치합니다(이렇게 하면 postinstall을 통해 js도 빌드됩니다):
npm install
Google Cloud Console에서 Google OAuth 자격 증명을 다운로드하고("자격 증명" 아래), 파일 이름을 gcp-oauth.keys.json 으로 바꾸어 프로젝트의 루트 디렉토리에 넣습니다.
- 파일에 "데스크톱 앱"에 대한 자격 증명이 포함되어 있는지 확인하세요.
- 또는 제공된 템플릿 파일인 cp gcp-oauth.keys.example.json gcp-oauth.keys.json 복사하여 Google Cloud Console에서 사용자 인증 정보로 채웁니다.

사용 가능한 스크립트

npm run build - TypeScript 코드 빌드( src 컴파일하여 build )
npm run typecheck - 컴파일하지 않고 TypeScript 유형 검사 실행
npm run start - 컴파일된 MCP 서버 시작( node build/index.js 사용)
npm run auth - Google OAuth 인증 흐름을 수동으로 실행합니다.
npm test - Vitest를 사용하여 단위/통합 테스트 모음을 실행합니다.
npm run test:watch - watch 모드에서 테스트 실행
npm run coverage - 테스트 실행 및 커버리지 보고서 생성

입증

서버는 Google OAuth 2.0 인증을 처리하여 캘린더 데이터에 액세스합니다.

자동 인증 흐름(서버 시작 중)

gcp-oauth.keys.json 의 이름이 올바르게 지정되고 프로젝트 루트에 배치되었는지 확인하세요.
MCP 서버를 시작합니다: npm start .
서버는 .gcp-saved-tokens.json 에 존재하는 유효한 인증 토큰이 있는지 확인합니다.
유효한 토큰이 발견되면 서버는 정상적으로 시작됩니다.
유효한 토큰이 발견되지 않으면:
- 서버가 임시 로컬 웹 서버를 시작하려고 시도합니다(포트 3000-3004 시도).
- 기본 웹 브라우저에서 자동으로 Google 계정 로그인 및 동의 화면이 열립니다.
- 브라우저의 지시에 따라 애플리케이션을 승인하세요.
- 인증이 성공적으로 완료되면 로컬 페이지(예: http://localhost:3000/oauth2callback )로 리디렉션됩니다.
- 이 페이지에는 토큰이 .gcp-saved-tokens.json 에 저장되었음을 확인하는 성공 메시지가 표시됩니다(정확한 파일 경로도 표시됨).
- 임시 인증 서버가 자동으로 종료됩니다.
- 메인 MCP 서버가 시작 프로세스를 계속합니다.

수동 인증 흐름

다시 인증해야 하거나 별도로 인증을 처리하려는 경우:

명령을 실행하세요: npm run auth
이 스크립트는 위에 설명된 것과 동일한 브라우저 기반 인증 흐름을 수행합니다.
브라우저가 열리고 인증을 하면 토큰이 저장된 위치를 나타내는 성공 페이지가 표시됩니다.
인증이 성공하면 스크립트가 자동으로 종료됩니다.

토큰 관리

인증 토큰은 프로젝트 루트의 .gcp-saved-tokens.json 에 저장됩니다.
이 파일은 자동으로 생성되므로 버전 제어에 커밋하면 안 됩니다( .gitignore 에 포함됨).
서버는 저장된 새로 고침 토큰을 사용하여 만료된 액세스 토큰을 자동으로 새로 고치려고 시도합니다.
새로 고침 토큰 자체가 만료되거나(예: Google Cloud 앱이 테스트 모드인 경우 7일 후) 취소된 경우 자동 흐름(서버를 다시 시작)이나 수동 npm run auth 명령을 사용하여 다시 인증해야 합니다.

테스트

단위 테스트와 통합 테스트는 Vitest를 사용하여 구현됩니다.

테스트 실행: npm test
감시 모드에서 테스트 실행: npm run test:watch
커버리지 보고서 생성: npm run coverage

서버 로직과 핸들러의 분리된 테스트를 보장하기 위해 모의 외부 종속성(Google API, 파일 시스템)을 테스트합니다.

보안 참고 사항

서버는 로컬에서 실행되며 OAuth 인증이 필요합니다.
OAuth 사용자 인증 정보( gcp-oauth.keys.json )와 저장된 토큰( .gcp-saved-tokens.json )은 버전 관리 시스템에 커밋해서는 안 됩니다. .gitignore 파일에 추가해야 합니다.
프로덕션 환경에서 사용하려면 Google에서 OAuth 애플리케이션을 검증받는 것이 좋습니다.

Claude Desktop과 함께 사용

Claude Desktop 구성 파일에 다음 구성을 추가하세요. 예: /Users/<user>/Library/Application Support/Claude/claude_desktop_config.json
{ "mcpServers": { "google-calendar": { "command": "node", "args": ["<absolute-path-to-project-folder>/build/index.js"] } } }
참고: <absolute-path-to-project-folder> 프로젝트 디렉토리의 실제 경로로 바꾸세요.
Claude Desktop을 다시 시작하세요

개발

문제 해결

인증 오류/콜백 시 연결 재설정:
- gcp-oauth.keys.json 존재하고 데스크톱 앱 유형에 대한 자격 증명을 포함하고 있는지 확인하세요.
- Google Cloud OAuth 동의 화면 설정에서 사용자 이메일이 테스트 사용자 로 추가되었는지 확인하세요(변경 사항이 전파되는 데 몇 분 정도 걸릴 수 있습니다).
- .gcp-saved-tokens.json 삭제하고 다시 인증해보세요( npm run auth 또는 restart npm start ).
- 인증이 필요할 때 다른 프로세스가 3000-3004 포트를 차단하고 있지 않은지 확인하세요.
토큰은 매주 만료됩니다.
- Google Cloud 앱이 테스트 모드인 경우, 갱신 토큰은 7일 후에 만료됩니다. 필요한 경우 다시 인증하세요.
- 더 오래 지속되는 새로 고침 토큰을 위해 Google Cloud Console에서 앱을 프로덕션 으로 옮기는 것을 고려하세요(Google에서 확인이 필요함).
빌드 오류:
- npm install 다시 실행하세요.
- Node.js 버전을 확인하세요(LTS 사용).
- build/ 디렉토리를 삭제하고 npm run build 실행합니다.

특허

MIT

google-calendar-mcp

Integrations