Google Workspace MCP Server

Сервер Google Workspace MCP

Подключите клиентов MCP, помощников AI и многое другое к сервисам Google Workspace через протокол контекста модели

Посмотрите на это в действии:

📑 Содержание

• Обзор
• Функции
• Быстрый старт
  • Предпосылки
  • Установка
  • Конфигурация
  • Запустить сервер
  • Подключение к серверу
  • Интеграция с Open WebUI
  • Первая аутентификация
• Доступные инструменты
  • Календарь
  • Google Диск
  • Gmail
  • Google Документы
• Разработка
  • Структура проекта
  • Обработка портов для OAuth
  • Отладка
  • Добавление новых инструментов
• Заметки о безопасности
• Лицензия

🌐 Обзор

Google Workspace MCP Server интегрирует службы Google Workspace (Календарь, Диск, Gmail и Документы) с помощниками ИИ и другими приложениями с помощью Model Context Protocol (MCP). Это позволяет системам ИИ получать доступ и взаимодействовать с пользовательскими данными из приложений Google Workspace безопасно и эффективно.

✨ Особенности

• 🔐 Аутентификация OAuth 2.0 : безопасное подключение к API Google с использованием авторизованных пользователем учетных данных с автоматическим обновлением токенов и централизованным потоком аутентификации.
• 📅 Интеграция с Google Calendar : полное управление календарем — список календарей, выбор событий, создание/изменение/удаление событий с поддержкой событий на весь день и событий с заданным временем
• 📁 Интеграция с Google Drive : поиск файлов, просмотр содержимого папок, чтение содержимого файлов и создание новых файлов. Поддержка извлечения и восстановления .docx, .xlsx и других форматов Microsoft Office нативно!
• 📧 Интеграция с Gmail : полное управление электронной почтой — поиск сообщений, извлечение контента, отправка писем и создание черновиков с полной поддержкой всех синтаксисов запросов
• 📄 Интеграция с Google Docs : ищите документы, читайте их содержимое, создавайте списки документов в папках и создавайте новые документы прямо из чата!
• 🔄 Несколько вариантов транспортировки : потоковая передача HTTP + резервный SSE
• 🔌 Совместимость mcpo : легкое предоставление сервера в качестве конечной точки OpenAPI для интеграции с такими инструментами, как Open WebUI.
• 🧩 Расширяемый дизайн : простая структура для добавления поддержки большего количества API и инструментов Google Workspace
• 🔄 Интегрированный обратный вызов OAuth : обрабатывает перенаправление OAuth непосредственно на сервере на порту 8000
• ⚡ Потокобезопасное управление сеансами : надежная обработка сеансов с потокобезопасной архитектурой для повышения надежности

🚀 Быстрый старт

Предпосылки

• Питон 3.11+
• Установщик пакета uv (или pip)
• Проект Google Cloud с включенными учетными данными OAuth 2.0 для требуемых API (Календарь, Диск, Gmail, Документы)

Установка

Конфигурация

1. Создайте учетные данные OAuth 2.0 (тип приложения для настольного компьютера) в Google Cloud Console .
2. Включите API Google Calendar , API Google Drive , API Gmail и API Google Docs для своего проекта.
3. Загрузите учетные данные клиента OAuth как client_secret.json и поместите его в корневой каталог проекта.
4. Добавьте следующий URI перенаправления в конфигурацию клиента OAuth в Google Cloud Console. Обратите внимание, что http://localhost:8000 — это базовый URI и порт по умолчанию, которые можно настроить с помощью переменных среды ( WORKSPACE_MCP_BASE_URI и WORKSPACE_MCP_PORT ). Если вы измените их, вам необходимо обновить URI перенаправления в Google Cloud Console соответствующим образом.
   http://localhost:8000/oauth2callback
5. ⚠️ Важно : убедитесь, что client_secret.json добавлен в ваш файл .gitignore и никогда не передается в систему контроля версий.

Конфигурация сервера

Базовый URL-адрес и порт сервера можно настроить с помощью переменных среды:

• WORKSPACE_MCP_BASE_URI : Устанавливает базовый URI для сервера (по умолчанию: http://localhost ). Это влияет на server_url , используемый для вызова собственных функций Gemini, и OAUTH_REDIRECT_URI .
• WORKSPACE_MCP_PORT : Устанавливает порт, который прослушивает сервер (по умолчанию: 8000 ). Это влияет на server_url , port и OAUTH_REDIRECT_URI .

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

Настройка среды

Сервер использует HTTP для обратных вызовов OAuth localhost во время разработки. Установите эту переменную среды перед запуском сервера:

Без этого вы можете столкнуться с ошибкой «OAuth 2 MUST use HTTPS» во время процесса аутентификации.

Запустить сервер

Выберите один из следующих способов запуска сервера:

Запускает сервер с транспортным уровнем HTTP на порту 8000.

Многопользовательский MCP — это своего рода беспорядок, поэтому сейчас все работает лучше всего как сопоставление 1:1 между клиентом и сервером. Это изменится, как только Клод сможет выполнять потоки OAuth 2.1, поэтому этот MCP был создан с флагом для упрощенных однопользовательских сред. Вы можете запустить сервер в однопользовательском режиме, который обходит сопоставление сеанса с OAuth и использует любые доступные учетные данные из каталога .credentials :

В однопользовательском режиме:

• Сервер автоматически находит и использует любые действительные учетные данные в каталоге .credentials
• Сопоставление сеансов не требуется — сервер использует первый найденный действительный файл учетных данных.
• Полезно для разработки, тестирования или однопользовательских развертываний.
• Для создания файлов учетных данных по-прежнему требуется первоначальная аутентификация OAuth

Этот режим особенно полезен, когда вам не требуется управление многопользовательскими сеансами и требуется упрощенная обработка учетных данных.

Вы можете создать и запустить сервер, используя предоставленный Dockerfile .

Файл smithery.yaml настроен для корректного запуска сервера в контейнере Docker.

Важные порты

Порты по умолчанию — 8000 , но их можно изменить с помощью переменной среды WORKSPACE_MCP_PORT .

Подключение к серверу

Сервер поддерживает несколько способов подключения:

Клод Рабочий стол:

Может работать где угодно и использоваться через mcp-remote или вызываться локально либо с помощью uv run main.py в качестве аргумента, либо с помощью mcp-remote с localhost.

config.json:

1. Установите mcpo : uv pip install mcpo или pip install mcpo
2. Создайте config.json (см. Интеграция с Open WebUI )
3. Запустите mcpo , указав на вашу конфигурацию: uvx mcpo --config config.json --port 8001
4. API сервера MCP будет доступен по адресу: http://localhost:8001/google_workspace (или по имени, указанному в config.json )
5. Документация OpenAPI (Swagger UI) доступна по адресу: http://localhost:8001/google_workspace/docs

С командой запуска (для использования mcpo с одним mcp):

1. Установите mcpo : uv pip install mcpo или pip install mcpo
2. Запустите с uvx mcpo --port 8001 --api-key "top-secret" --server-type "streamablehttp" -- http://localhost:8000/mcp
3. API сервера MCP будет доступен по адресу: http://localhost:8001/openapi.json (или по имени, указанному в config.json )
4. Документация OpenAPI (Swagger UI) доступна по адресу: http://localhost:8001/docs
5. Запустите сервер в режиме HTTP (см. Запуск сервера )
6. Отправляйте запросы MCP JSON напрямую на http://localhost:8000
7. Полезно для тестирования с помощью таких инструментов, как curl или пользовательских HTTP-клиентов.
8. Может использоваться для обслуживания Claude Desktop и других клиентов MCP, которые еще не интегрировали новый потоковый HTTP-транспорт через mcp-remote:
9. При желании вы также можете работать в резервном режиме SSE.

Интеграция с Open WebUI

Чтобы использовать этот сервер в качестве поставщика инструментов в Open WebUI:

1. Создайте конфигурацию mcpo : создайте файл с именем config.json со следующей структурой, чтобы mcpo сделал потоковую конечную точку HTTP доступной в качестве инструмента спецификации OpenAPI.
   { "mcpServers": { "google_workspace": { "type": "streamablehttp", "url": "http://localhost:8000/mcp" } } }
2. Запустите сервер mcpo :
   mcpo --port 8001 --config config.json --api-key "your-optional-secret-key"
   Эта команда запускает прокси-сервер mcpo , обслуживающий ваш активный (предполагается, что порт 8000) Google Workspace MCP на порту 8001.
3. Настройте Open WebUI :
   • Перейдите к настройкам Open WebUI.
   • Перейдите в «Подключения» -> «Инструменты»
   • Нажмите «Добавить инструмент».
   • Введите URL-адрес сервера: http://localhost:8001/google_workspace (соответствующий базовому URL-адресу mcpo и имени сервера из config.json )
   • Если вы использовали --api-key с mcpo , введите его в качестве API-ключа
   • Сохранить конфигурацию
   • Инструменты Google Workspace теперь должны быть доступны при взаимодействии с моделями в Open WebUI.

Первая аутентификация

При вызове инструмента, требующего доступа к API Google:

• Если user_google_email предоставлен инструменту, а учетные данные отсутствуют/недействительны : сервер автоматически инициирует поток OAuth 2.0. URL-адрес авторизации будет возвращен в ответе MCP (или выведен на консоль).
• Если user_google_email НЕ предоставлен и учетные данные отсутствуют/недействительны : инструмент вернет сообщение об ошибке, указывающее LLM использовать централизованный инструмент start_google_auth . Затем LLM должен вызвать start_google_auth с адресом электронной почты пользователя и соответствующим service_name (например, «Google Calendar», «Google Docs», «Gmail», «Google Drive»). Это также вернет URL авторизации.

Действия пользователя (после получения URL-адреса авторизации):

1. Откройте предоставленный URL-адрес авторизации в веб-браузере.
2. Войдите в учетную запись Google и предоставьте запрошенные разрешения для указанной службы.
3. После авторизации Google перенаправит браузер на http://localhost:8000/oauth2callback (или на настроенный вами URI перенаправления).
4. Сервер MCP обрабатывает этот обратный вызов, обменивает код авторизации на токены и надежно сохраняет учетные данные.
5. Затем LLM может повторить исходный запрос. Последующие вызовы для того же пользователя и сервиса должны работать без повторной аутентификации до тех пор, пока не истечет срок действия маркера обновления или он не будет отозван.

🧰 Доступные инструменты

Примечание : Первое использование любого инструмента для определенной службы Google может запустить поток аутентификации OAuth, если действительные учетные данные еще не сохранены и user_google_email предоставлен инструменту. Если требуется аутентификация и user_google_email не предоставлен инструменту, LLM должен использовать централизованный инструмент start_google_auth (определенный в core/server.py ) с электронной почтой пользователя и соответствующим service_name .

📅 Google Календарь

Источник: gcalendar/calendar_tools.py

ℹ️ Все инструменты Календаря поддерживают аутентификацию через текущий сеанс MCP ( mcp_session_id ) или откат к user_google_email . Если ни один из них недоступен и требуется аутентификация, инструмент вернет ошибку, предлагающую LLM использовать централизованный инструмент start_google_auth с электронной почтой пользователя и service_name="Google Calendar" .

🕒 Параметры даты/времени: инструменты принимают как полные временные метки RFC3339 (например, 2024-05-12T10:00:00Z), так и простые даты (например, 2024-05-12). Сервер автоматически форматирует их по мере необходимости.

📁 Google Диск

Источник: gdrive/drive_tools.py

Синтаксис запроса : для поисковых запросов Google Диска см. Синтаксис поискового запроса Диска.

📧 Gmail

Источник: gmail/gmail_tools.py

Синтаксис запроса : для поисковых запросов Gmail см. Синтаксис поискового запроса Gmail

📝 Google Документы

Источник: gdocs/docs_tools.py

🛠️ Развитие

Структура проекта

Обработка портов для OAuth

Сервер умело обрабатывает URI перенаправления OAuth 2.0 ( /oauth2callback ), не требуя отдельной структуры веб-сервера:

• Он использует встроенные возможности HTTP-сервера базовой библиотеки MCP при работе в режиме HTTP или через mcpo
• Пользовательский маршрут MCP зарегистрирован специально для /oauth2callback на порту 8000
• Когда Google перенаправляет пользователя обратно после авторизации, сервер MCP перехватывает запрос по этому маршруту
• Модуль auth извлекает код авторизации и завершает обмен токенами.
• Для этого необходимо установить OAUTHLIB_INSECURE_TRANSPORT=1 при локальном запуске, поскольку обратный вызов использует http://localhost

Отладка

Проверьте mcp_server_debug.log на наличие подробных журналов, включая шаги аутентификации и вызовы API. При необходимости включите отладочное ведение журнала.

• Проверьте правильность и наличие client_secret.json
• Убедитесь, что в Google Cloud Console настроен правильный URI перенаправления ( http://localhost:8000/oauth2callback ).
• Убедитесь, что необходимые API (Календарь, Диск, Gmail) включены в вашем проекте Google Cloud.
• Проверьте, что в среде, где выполняется серверный процесс, установлен OAUTHLIB_INSECURE_TRANSPORT=1
• Ищите конкретные сообщения об ошибках во время процесса OAuth на основе браузера.

Проверьте журналы сервера на наличие трассировок или сообщений об ошибках, возвращаемых API Google.

Добавление новых инструментов

1. Выберите или создайте соответствующий модуль (например, gdocs/gdocs_tools.py )
2. Импортировать необходимые библиотеки (клиентскую библиотеку Google API и т. д.)
3. Определите async функцию для логики вашего инструмента. Используйте подсказки типов для параметров
4. Украсьте функцию с помощью @server.tool("your_tool_name")
5. Внутри функции получите аутентифицированные учетные данные:

6. Создайте клиент службы API Google: service = build('drive', 'v3', credentials=credentials)
7. Реализовать логику вызова API Google
8. Грамотно обрабатывайте потенциальные ошибки
9. Возвращает результаты в виде словаря или списка, сериализуемого в формате JSON.
10. Импортируйте функцию инструмента в main.py , чтобы она была зарегистрирована на сервере.
11. Определите необходимые константы области действия, специфичные для сервиса, в модуле вашего инструмента.
12. Обновите pyproject.toml если требуются новые зависимости.

Управление областью действия : глобальный список SCOPES в config/google_config.py используется для начального экрана согласия OAuth. Отдельные инструменты должны запрашивать минимальные required_scopes которые им нужны, при вызове get_credentials .

🔒 Заметки о безопасности

• client_secret.json : Этот файл содержит конфиденциальные учетные данные. НИКОГДА не передавайте его в систему контроля версий. Убедитесь, что он указан в вашем файле .gitignore . Сохраните его в безопасности.
• Токены пользователя : аутентифицированные учетные данные пользователя (токены обновления) хранятся локально в файлах типа credentials-<user_id_hash>.json . Защитите эти файлы, поскольку они предоставляют доступ к данным учетной записи Google пользователя. Убедитесь, что они также находятся в .gitignore .
• Безопасность обратного вызова OAuth : использование http://localhost для обратного вызова OAuth является стандартным для установленных приложений во время разработки, но требует OAUTHLIB_INSECURE_TRANSPORT=1 . Для производственных развертываний за пределами localhost вы ДОЛЖНЫ использовать HTTPS для URI обратного вызова и настроить его соответствующим образом в Google Cloud Console.
• Безопасность mcpo : При использовании mcpo для предоставления доступа к серверу по сети учтите следующее:
  • Использование опции --api-key для базовой аутентификации
  • Запуск mcpo за обратным прокси-сервером (например, Nginx или Caddy) для обработки HTTPS-терминации, надлежащего ведения журнала и более надежной аутентификации.
  • Привязка mcpo только к доверенным сетевым интерфейсам, если он доступен за пределами localhost
• Управление областью действия : сервер запрашивает определенные области действия OAuth (разрешения) для Календаря, Диска и Gmail. Пользователи предоставляют доступ на основе этих областей действия во время первоначальной аутентификации. Не запрашивайте более широкие области действия, чем необходимо для реализованных инструментов.

Скриншоты:

📄 Лицензия

Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE .