Сервер Google Workspace MCP
Подключите клиентов MCP, помощников AI и многое другое к сервисам Google Workspace через протокол контекста модели
Посмотрите на это в действии:
📑 Содержание
🌐 Обзор
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, Документы)
Установка
Конфигурация
- Создайте учетные данные OAuth 2.0 (тип приложения для настольного компьютера) в Google Cloud Console .
- Включите API Google Calendar , API Google Drive , API Gmail и API Google Docs для своего проекта.
- Загрузите учетные данные клиента OAuth как
client_secret.json
и поместите его в корневой каталог проекта. - Добавьте следующий URI перенаправления в конфигурацию клиента OAuth в Google Cloud Console. Обратите внимание, что
http://localhost:8000
— это базовый URI и порт по умолчанию, которые можно настроить с помощью переменных среды (WORKSPACE_MCP_BASE_URI
иWORKSPACE_MCP_PORT
). Если вы измените их, вам необходимо обновить URI перенаправления в Google Cloud Console соответствующим образом. - ⚠️ Важно : убедитесь, что
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
.
Услуга | Порт по умолчанию | Описание |
---|---|---|
Обратный вызов OAuth | 8000 | Обрабатывается внутри сервера через маршрут /oauth2callback |
HTTP-сервер режима | 8000 | По умолчанию при использовании HTTP-транспорта |
Подключение к серверу
Сервер поддерживает несколько способов подключения:
Клод Рабочий стол:
Может работать где угодно и использоваться через
mcp-remote
или вызываться локально либо с помощьюuv run main.py
в качестве аргумента, либо с помощьюmcp-remote
с localhost.
config.json:
- Установите
mcpo
:uv pip install mcpo
илиpip install mcpo
- Создайте
config.json
(см. Интеграция с Open WebUI ) - Запустите
mcpo
, указав на вашу конфигурацию:uvx mcpo --config config.json --port 8001
- API сервера MCP будет доступен по адресу:
http://localhost:8001/google_workspace
(или по имени, указанному вconfig.json
) - Документация OpenAPI (Swagger UI) доступна по адресу:
http://localhost:8001/google_workspace/docs
С командой запуска (для использования mcpo с одним mcp):
- Установите
mcpo
:uv pip install mcpo
илиpip install mcpo
- Запустите с
uvx mcpo --port 8001 --api-key "top-secret" --server-type "streamablehttp" -- http://localhost:8000/mcp
- API сервера MCP будет доступен по адресу:
http://localhost:8001/openapi.json
(или по имени, указанному вconfig.json
) - Документация OpenAPI (Swagger UI) доступна по адресу:
http://localhost:8001/docs
- Запустите сервер в режиме HTTP (см. Запуск сервера )
- Отправляйте запросы MCP JSON напрямую на
http://localhost:8000
- Полезно для тестирования с помощью таких инструментов, как
curl
или пользовательских HTTP-клиентов. - Может использоваться для обслуживания Claude Desktop и других клиентов MCP, которые еще не интегрировали новый потоковый HTTP-транспорт через mcp-remote:
- При желании вы также можете работать в резервном режиме SSE.
Интеграция с Open WebUI
Чтобы использовать этот сервер в качестве поставщика инструментов в Open WebUI:
- Создайте конфигурацию
mcpo
: создайте файл с именемconfig.json
со следующей структурой, чтобы mcpo сделал потоковую конечную точку HTTP доступной в качестве инструмента спецификации OpenAPI. - Запустите сервер
mcpo
:Эта команда запускает прокси-серверmcpo
, обслуживающий ваш активный (предполагается, что порт 8000) Google Workspace MCP на порту 8001. - Настройте 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-адреса авторизации):
- Откройте предоставленный URL-адрес авторизации в веб-браузере.
- Войдите в учетную запись Google и предоставьте запрошенные разрешения для указанной службы.
- После авторизации Google перенаправит браузер на
http://localhost:8000/oauth2callback
(или на настроенный вами URI перенаправления). - Сервер MCP обрабатывает этот обратный вызов, обменивает код авторизации на токены и надежно сохраняет учетные данные.
- Затем LLM может повторить исходный запрос. Последующие вызовы для того же пользователя и сервиса должны работать без повторной аутентификации до тех пор, пока не истечет срок действия маркера обновления или он не будет отозван.
🧰 Доступные инструменты
Примечание : Первое использование любого инструмента для определенной службы Google может запустить поток аутентификации OAuth, если действительные учетные данные еще не сохранены и
user_google_email
предоставлен инструменту. Если требуется аутентификация иuser_google_email
не предоставлен инструменту, LLM должен использовать централизованный инструментstart_google_auth
(определенный вcore/server.py
) с электронной почтой пользователя и соответствующимservice_name
.
📅 Google Календарь
Источник: gcalendar/calendar_tools.py
Инструмент | Описание | Параметры |
---|---|---|
start_google_auth | (Централизовано в core/server.py ) Инициирует поток аутентификации OAuth 2.0 для определенной учетной записи и службы Google. Используйте это, когда нет действительных учетных данных или если инструмент не работает из-за отсутствия аутентификации и ему не был предоставлен адрес электронной почты. | • user_google_email (обязательно): адрес электронной почты пользователя Google. • service_name (обязательно): имя службы Google (например, «Google Calendar», «Google Docs», «Gmail», «Google Drive»). |
list_calendars | Перечисляет все календари, доступные аутентифицированному пользователю. | • user_google_email (необязательно): используется, если сеанс не аутентифицирован • mcp_session_id (вводится автоматически) |
get_events | Извлекает предстоящие события из указанного календаря в указанном диапазоне времени. | • calendar_id (необязательно): идентификатор календаря (по умолчанию: primary ) • time_min (необязательно): время начала (RFC3339 или YYYY-MM-DD ) • time_max (необязательно): время окончания (RFC3339 или YYYY-MM-DD ) • max_results (необязательно): максимальное количество событий (по умолчанию: 25) • user_google_email (необязательно) • mcp_session_id (вставляется автоматически) |
create_event | Создает новое событие календаря. Поддерживает события на весь день и события с заданным временем. | • summary (обязательно): Название события• start_time (обязательно): Время начала (RFC3339 или YYYY-MM-DD )• end_time (обязательно): Время окончания (RFC3339 или YYYY-MM-DD )• calendar_id (необязательно): Идентификатор календаря (по умолчанию: primary )• description , location , attendees , timezone (необязательно)• user_google_email (необязательно)• mcp_session_id (вставляется автоматически) |
modify_event | Обновляет существующее событие по ID. Будут изменены только предоставленные поля. | • event_id (обязательно): идентификатор события для изменения • calendar_id (необязательно): идентификатор календаря (по умолчанию: primary ) • summary , start_time , end_time , description , location , attendees , timezone (необязательно) • user_google_email (необязательно) • mcp_session_id (вставляется автоматически) |
delete_event | Удаляет событие по идентификатору. | • event_id (обязательно): идентификатор события для удаления • calendar_id (необязательно): идентификатор календаря (по умолчанию: primary ) • user_google_email (необязательно) • mcp_session_id (вставляется автоматически) |
ℹ️ Все инструменты Календаря поддерживают аутентификацию через текущий сеанс 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
Инструмент | Описание | Параметры |
---|---|---|
search_drive_files | Поиск файлов и папок на Диске пользователя. | • query (обязательно): строка поискового запроса (например, name contains 'report' ) • max_results (необязательно): максимальное количество возвращаемых файлов |
get_drive_file_content | Извлекает содержимое определенного файла | • file_id (обязательно): идентификатор файла. • mime_type (необязательно): укажите желаемый формат экспорта. |
list_drive_items | Выводит список файлов и папок в определенной папке или корне | • folder_id (необязательно): идентификатор папки для отображения (по умолчанию — root) • max_results (необязательно): максимальное количество возвращаемых элементов |
create_drive_file | Создает новый файл на Google Диске | • name (обязательно): желаемое имя для нового файла. • content (обязательно): текстовое содержимое для записи в файл. • folder_id (необязательно): идентификатор родительской папки. • mime_type (необязательно): тип MIME файла (по умолчанию text/plain ). |
Синтаксис запроса : для поисковых запросов Google Диска см. Синтаксис поискового запроса Диска.
📧 Gmail
Источник: gmail/gmail_tools.py
Инструмент | Описание | Параметры |
---|---|---|
search_gmail_messages | Поиск сообщений электронной почты с использованием стандартных операторов поиска Gmail (от, тема и т. д.). | • query (обязательно): строка поиска (например, "from:foo subject:bar is:unread" ) • user_google_email (необязательно) • page_size (необязательно, по умолчанию: 10) • mcp_session_id (вставляется автоматически) |
get_gmail_message_content | Получите тему, отправителя и текст письма по идентификатору сообщения. | • message_id (обязательно)• user_google_email (необязательно)• mcp_session_id (вставляется автоматически) |
send_gmail_message | Отправьте текстовое электронное письмо, используя учетную запись Gmail пользователя. | • to (обязательно): Адрес электронной почты получателя • subject (обязательно) • body (обязательно) • user_google_email (необязательно) • mcp_session_id (вставляется автоматически) |
draft_gmail_message | Создайте черновик электронного письма в аккаунте Gmail пользователя. | • subject (обязательно): Тема письма• body (обязательно): Тело письма (обычный текст)• to (необязательно): Адрес электронной почты получателя• user_google_email (необязательно)• mcp_session_id (вставляется автоматически) |
Синтаксис запроса : для поисковых запросов Gmail см. Синтаксис поискового запроса Gmail
📝 Google Документы
Источник: gdocs/docs_tools.py
Инструмент | Описание | Параметры |
---|---|---|
search_docs | Поиск Google Docs по названию (с использованием Drive API). | • query (обязательно): Текст для поиска в именах документов • user_google_email (необязательно) • page_size (необязательно, по умолчанию: 10) • mcp_session_id (вставляется автоматически) |
get_doc_content | Извлечение текстового содержимого документа Google по его идентификатору. | • document_id (обязательно)• user_google_email (необязательно)• mcp_session_id (вставляется автоматически) |
list_docs_in_folder | Вывести список всех документов Google в указанной папке Диска (по идентификатору папки, по умолчанию = root ). | • folder_id (необязательно, по умолчанию: 'root' ) • user_google_email (необязательно) • page_size (необязательно, по умолчанию: 100) • mcp_session_id (вставляется автоматически) |
create_doc | Создайте новый документ Google, при желании с исходным содержимым. | • title (обязательно): Имя документа • content (необязательно, по умолчанию: пусто) • user_google_email (необязательно) • mcp_session_id (вставляется автоматически) |
🛠️ Развитие
Структура проекта
Обработка портов для 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.
Добавление новых инструментов
- Выберите или создайте соответствующий модуль (например,
gdocs/gdocs_tools.py
) - Импортировать необходимые библиотеки (клиентскую библиотеку Google API и т. д.)
- Определите
async
функцию для логики вашего инструмента. Используйте подсказки типов для параметров - Украсьте функцию с помощью
@server.tool("your_tool_name")
- Внутри функции получите аутентифицированные учетные данные:
- Создайте клиент службы API Google:
service = build('drive', 'v3', credentials=credentials)
- Реализовать логику вызова API Google
- Грамотно обрабатывайте потенциальные ошибки
- Возвращает результаты в виде словаря или списка, сериализуемого в формате JSON.
- Импортируйте функцию инструмента в
main.py
, чтобы она была зарегистрирована на сервере. - Определите необходимые константы области действия, специфичные для сервиса, в модуле вашего инструмента.
- Обновите
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
.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
Сервер Google Workspace MCP
Related MCP Servers
- -securityAlicense-qualityMCP server to interact with Google produts.Last updated -270PythonMIT License
- Python
- MIT License
- AsecurityAlicenseAqualityWayback Machine MCP ServerLast updated -23TypeScriptMIT License