Google Calendar MCP

Сервер MCP Календаря Google

Это сервер Model Context Protocol (MCP), который обеспечивает интеграцию с Google Calendar. Он позволяет LLM читать, создавать, обновлять и искать события календаря через стандартизированный интерфейс.

Пример использования

Наряду с обычными возможностями, которые вы ожидаете от интеграции календаря, вы также можете выполнять действительно динамичные, многошаговые процессы, такие как:

1. Добавьте события из снимков экрана и изображений:
   Add this event to my calendar based on the attached screenshot.
   Поддерживаемые форматы изображений: PNG, JPEG, GIF Изображения могут содержать сведения о событиях, такие как дата, время, место и описание.
2. Анализ календаря:
   What events do I have coming up this week that aren't part of my usual routine?
3. Проверить посещаемость:
   Which events tomorrow have attendees who have not accepted the invitation?
4. Автоматическая координация событий:
   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.
5. Укажите свою доступность:
   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. Node.js (рекомендуется последняя LTS-версия)
2. TypeScript 5.3 или выше
3. Проект Google Cloud с включенным API Календаря
4. Учетные данные OAuth 2.0 (идентификатор клиента и секретный ключ клиента)

Настройка Google Cloud

1. Перейдите в Google Cloud Console.
2. Создайте новый проект или выберите существующий.
3. Включите API Google Calendar для вашего проекта. Убедитесь, что на верхней панели выбран нужный проект, прежде чем включать API.
4. Создайте учетные данные OAuth 2.0:
   • Перейти к учетным данным
   • Нажмите «Создать учетные данные» > «Идентификатор клиента OAuth».
   • Выберите «Пользовательские данные» для типа данных, к которым приложение будет иметь доступ.
   • Добавьте название вашего приложения и контактную информацию
   • Добавьте следующие области (необязательно):
     • https://www.googleapis.com/auth/calendar.events (или более широко https://www.googleapis.com/auth/calendar при необходимости)
   • Выберите «Приложение для ПК» в качестве типа приложения (Важно!)
   • Добавьте свой адрес электронной почты в качестве тестового пользователя на экране согласия OAuth.
     • Примечание: добавление тестового пользователя займет несколько минут. Согласие OAuth не позволит вам продолжить, пока тестовый пользователь не распространится.
     • Примечание о тестовом режиме: пока приложение находится в тестовом режиме, токены аутентификации истекают через 1 неделю и их необходимо обновить, выполнив npm run auth .

Установка

1. Клонировать репозиторий
2. Установка зависимостей (это также собирает js через postinstall):
   npm install
3. Загрузите учетные данные Google OAuth из консоли Google Cloud Console (в разделе «Учетные данные»), переименуйте файл в 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 — запуск тестов в режиме наблюдения
• npm run coverage — запуск тестов и создание отчета о покрытии

Аутентификация

Сервер обрабатывает аутентификацию Google OAuth 2.0 для доступа к данным вашего календаря.

Автоматический поток аутентификации (во время запуска сервера)

1. Убедитесь, что gcp-oauth.keys.json правильно назван и помещен в корень проекта.
2. Запустите сервер MCP: npm start .
3. Сервер проверит наличие существующих действительных токенов аутентификации в .gcp-saved-tokens.json .
4. Если найдены действительные токены, сервер запускается в обычном режиме.
5. Если действительные токены не найдены:
   • Сервер пытается запустить временный локальный веб-сервер (пробует порты 3000-3004).
   • Ваш веб-браузер по умолчанию автоматически откроет экран входа в учетную запись Google и согласия.
   • Следуйте инструкциям в браузере для авторизации приложения.
   • После успешной авторизации вы будете перенаправлены на локальную страницу (например, http://localhost:3000/oauth2callback ).
   • На этой странице отобразится сообщение об успешном сохранении токенов в файле .gcp-saved-tokens.json (и будет указан точный путь к файлу).
   • Временный сервер аутентификации автоматически отключается.
   • Основной сервер MCP продолжает процесс запуска.

Ручной процесс аутентификации

Если вам необходимо пройти повторную аутентификацию или вы предпочитаете выполнять аутентификацию отдельно:

1. Выполните команду: npm run auth
2. Этот скрипт выполняет тот же процесс аутентификации на основе браузера, который описан выше.
3. Откроется ваш браузер, вы авторизуетесь и увидите страницу успешного завершения с указанием места сохранения токенов.
4. Скрипт автоматически завершит работу после успешной аутентификации.

Управление токенами

• Токены аутентификации хранятся в файле .gcp-saved-tokens.json в корне проекта.
• Этот файл создается автоматически и не должен передаваться в систему контроля версий (он включен в .gitignore ).
• Сервер пытается автоматически обновить просроченные токены доступа, используя сохраненный токен обновления.
• Если срок действия токена обновления истек (например, через 7 дней, если приложение Google Cloud находится в режиме тестирования) или он был отозван, вам потребуется повторно пройти аутентификацию, используя либо автоматический поток (перезапустив сервер), либо ручную команду 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 .
• Для использования в производственных целях рассмотрите возможность проверки вашего приложения OAuth в Google.

Использование с Claude Desktop

1. Добавьте эту конфигурацию в файл конфигурации 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> фактическим путем к каталогу вашего проекта.
2. Перезагрузить рабочий стол Клода

Разработка

Поиск неисправностей

1. Ошибки аутентификации/сброс соединения при обратном вызове:
   • Убедитесь, что gcp-oauth.keys.json существует и содержит учетные данные для типа приложения для настольного компьютера .
   • Убедитесь, что ваш адрес электронной почты добавлен в качестве тестового пользователя в настройках экрана согласия Google Cloud OAuth (подождите несколько минут, пока изменения вступят в силу).
   • Попробуйте удалить .gcp-saved-tokens.json и повторно выполнить аутентификацию ( npm run auth или restart npm start ).
   • Убедитесь, что никакой другой процесс не блокирует порты 3000–3004, когда требуется аутентификация.
2. Срок действия токенов истекает еженедельно:
   • Если ваше приложение Google Cloud находится в режиме тестирования , токены обновления истекают через 7 дней. При необходимости выполните повторную аутентификацию.
   • Рассмотрите возможность переноса вашего приложения в производственную среду в Google Cloud Console для получения более долговечных токенов обновления (требуется проверка Google).
3. Ошибки сборки:
   • Запустите npm install еще раз.
   • Проверьте версию Node.js (используйте LTS).
   • Удалите каталог build/ и запустите npm run build .

Если вы разработчик и хотите внести свой вклад в этот репозиторий, пожалуйста, ознакомьтесь с Обзором архитектуры перед внесением вклада.

Лицензия

Массачусетский технологический институт