Google Workspace MCP Server

Servidor MCP de Google Workspace

Conecte clientes MCP, asistentes de IA y más a los servicios de Google Workspace a través del Protocolo de contexto de modelo

Véalo en acción:

📑 Índice de contenidos

• Descripción general
• Características
• Inicio rápido
  • Prerrequisitos
  • Instalación
  • Configuración
  • Iniciar el servidor
  • Conectarse al servidor
  • Integración con Open WebUI
  • Autenticación por primera vez
• Herramientas disponibles
  • Calendario
  • Google Drive
  • Gmail
  • Documentos de Google
• Desarrollo
  • Estructura del proyecto
  • Manejo de puertos para OAuth
  • Depuración
  • Agregar nuevas herramientas
• Notas de seguridad
• Licencia

🌐 Descripción general

El servidor MCP de Google Workspace integra los servicios de Google Workspace (Calendario, Drive, Gmail y Documentos) con asistentes de IA y otras aplicaciones mediante el Protocolo de Contexto de Modelo (MCP). Esto permite que los sistemas de IA accedan e interactúen con los datos de los usuarios de las aplicaciones de Google Workspace de forma segura y eficiente.

✨ Características

• 🔐 Autenticación OAuth 2.0 : se conecta de forma segura a las API de Google mediante credenciales autorizadas por el usuario con actualización automática de tokens y flujo de autenticación centralizado
• Integración con Google Calendar : gestión completa del calendario: lista de calendarios, búsqueda de eventos, creación, modificación y eliminación de eventos con compatibilidad con eventos de día completo y temporizados
• Integración con Google Drive : Busca archivos, lista el contenido de carpetas, lee el contenido de archivos y crea nuevos. Admite la extracción y recuperación de archivos .docx, .xlsx y otros formatos de Microsoft Office de forma nativa.
• 📧 Integración con Gmail : gestión completa del correo electrónico: busque mensajes, recupere contenido, envíe correos electrónicos y cree borradores con soporte completo para todas las sintaxis de consulta
• Integración con Google Docs : busca documentos, lee su contenido, enumera documentos en carpetas y crea documentos nuevos directamente desde el chat.
• 🔄 Múltiples opciones de transporte : HTTP transmisible + respaldo SSE
• 🔌 Compatibilidad mcpo : exponga fácilmente el servidor como un punto final OpenAPI para la integración con herramientas como Open WebUI
• 🧩 Diseño extensible : Estructura simple para agregar compatibilidad con más API y herramientas de Google Workspace
• 🔄 Devolución de llamada OAuth integrada : maneja la redirección OAuth directamente dentro del servidor en el puerto 8000
• ⚡ Gestión de sesiones segura para subprocesos : gestión robusta de sesiones con arquitectura segura para subprocesos para una mayor confiabilidad

🚀 Inicio rápido

Prerrequisitos

• Python 3.11+
• Instalador del paquete uv (o pip)
• Proyecto de Google Cloud con credenciales OAuth 2.0 habilitadas para las API requeridas (Calendario, Drive, Gmail, Docs)

Instalación

Configuración

1. Cree credenciales OAuth 2.0 (tipo de aplicación de escritorio) en Google Cloud Console .
2. Habilite la API de Google Calendar , la API de Google Drive , la API de Gmail y la API de Google Docs para su proyecto.
3. Descargue las credenciales del cliente OAuth como client_secret.json y colóquelas en el directorio raíz del proyecto.
4. Añade la siguiente URI de redirección a la configuración de tu cliente OAuth en Google Cloud Console. Ten en cuenta que http://localhost:8000 es la URI base y el puerto predeterminados, que se pueden personalizar mediante las variables de entorno ( WORKSPACE_MCP_BASE_URI y WORKSPACE_MCP_PORT ). Si las modificas, debes actualizar la URI de redirección en Google Cloud Console según corresponda.
   http://localhost:8000/oauth2callback
5. ⚠️ Importante : asegúrese de que client_secret.json se agregue a su archivo .gitignore y nunca se confirme en el control de versiones.

Configuración del servidor

La URL base y el puerto del servidor se pueden personalizar mediante variables de entorno:

• WORKSPACE_MCP_BASE_URI : Establece la URI base del servidor (predeterminada: http://localhost ). Esto afecta a la server_url utilizada para las llamadas a funciones nativas de Gemini y a la OAUTH_REDIRECT_URI .
• WORKSPACE_MCP_PORT : Establece el puerto en el que escucha el servidor (predeterminado: 8000 ). Esto afecta a server_url , port y OAUTH_REDIRECT_URI .

Ejemplo de uso:

Configuración del entorno

El servidor usa HTTP para las devoluciones de llamadas OAuth del host local durante el desarrollo. Configure esta variable de entorno antes de ejecutar el servidor:

Sin esto, es posible que aparezca un error "OAuth 2 DEBE utilizar HTTPS" durante el flujo de autenticación.

Iniciar el servidor

Elija uno de los siguientes métodos para ejecutar el servidor:

Ejecuta el servidor con una capa de transporte HTTP en el puerto 8000.

El MCP multiusuario es un poco caótico, por lo que actualmente todo funciona mejor con una asignación 1:1 entre cliente y servidor. Esto cambiará en cuanto Claude pueda ejecutar flujos de OAuth 2.1, por lo que este MCP se creó con una opción para entornos monousuario simplificados. Puedes ejecutar el servidor en modo monousuario, lo que omite la asignación de sesión a OAuth y utiliza las credenciales disponibles del directorio .credentials .

En modo de usuario único:

• El servidor encuentra y utiliza automáticamente cualquier credencial válida en el directorio .credentials
• No se requiere mapeo de sesión: el servidor utiliza el primer archivo de credenciales válido que encuentra
• Útil para desarrollo, pruebas o implementaciones de usuario único.
• Aún requiere autenticación OAuth inicial para crear archivos de credenciales

Este modo es especialmente útil cuando no necesita administrar sesiones multiusuario y desea un manejo simplificado de credenciales.

Puede construir y ejecutar el servidor utilizando el Dockerfile proporcionado.

El archivo smithery.yaml está configurado para iniciar el servidor correctamente dentro del contenedor Docker.

Puertos importantes

Los puertos predeterminados son 8000 , pero se pueden cambiar mediante la variable de entorno WORKSPACE_MCP_PORT .

Conectarse al servidor

El servidor admite múltiples métodos de conexión:

Escritorio de Claude:

Se puede ejecutar en cualquier lugar y utilizar a través de mcp-remote o invocarse localmente con uv run main.py como argumento o utilizando mcp-remote con localhost.

config.json:

1. Instalar mcpo : uv pip install mcpo o pip install mcpo
2. Cree un config.json (consulte Integración con Open WebUI )
3. Ejecute mcpo apuntando a su configuración: uvx mcpo --config config.json --port 8001
4. La API del servidor MCP estará disponible en: http://localhost:8001/google_workspace (o el nombre definido en config.json )
5. Documentación de OpenAPI (Swagger UI) disponible en: http://localhost:8001/google_workspace/docs

Con comando de inicio (para uso de mcpo con un solo mcp):

1. Instalar mcpo : uv pip install mcpo o pip install mcpo
2. Comience con uvx mcpo --port 8001 --api-key "top-secret" --server-type "streamablehttp" -- http://localhost:8000/mcp
3. La API del servidor MCP estará disponible en: http://localhost:8001/openapi.json (o el nombre definido en config.json )
4. Documentación de OpenAPI (Swagger UI) disponible en: http://localhost:8001/docs
5. Inicie el servidor en modo HTTP (consulte Iniciar el servidor )
6. Envíe solicitudes JSON de MCP directamente a http://localhost:8000
7. Útil para realizar pruebas con herramientas como curl o clientes HTTP personalizados
8. Se puede utilizar para servir a Claude Desktop y otros clientes MCP que aún no han integrado el nuevo transporte HTTP Streamable a través de mcp-remote:
9. También puedes servir en modo de respaldo SSE si lo prefieres.

Integración con Open WebUI

Para utilizar este servidor como proveedor de herramientas dentro de Open WebUI:

1. Crear configuración mcpo : cree un archivo llamado config.json con la siguiente estructura para que mcpo haga que el punto final HTTP transmisible esté disponible como una herramienta de especificación de OpenAPI.
   { "mcpServers": { "google_workspace": { "type": "streamablehttp", "url": "http://localhost:8000/mcp" } } }
2. Inicie el servidor mcpo :
   mcpo --port 8001 --config config.json --api-key "your-optional-secret-key"
   Este comando inicia el proxy mcpo y atiende su MCP de Google Workspace activo (suponiendo el puerto 8000) en el puerto 8001.
3. Configurar Open WebUI :
   • Vaya a la configuración de Open WebUI
   • Vaya a "Conexiones" -> "Herramientas"
   • Haga clic en "Agregar herramienta"
   • Ingrese la URL del servidor: http://localhost:8001/google_workspace (que coincida con la URL base de mcpo y el nombre del servidor de config.json )
   • Si utilizó una --api-key con mcpo , ingrésela como clave API
   • Guardar la configuración
   • Las herramientas de Google Workspace ahora deberían estar disponibles al interactuar con modelos en Open WebUI

Autenticación por primera vez

Cuando se llama a una herramienta que requiere acceso a la API de Google:

• Si se proporciona user_google_email a la herramienta y las credenciales faltan o no son válidas , el servidor inicia automáticamente el flujo OAuth 2.0. Se devolverá una URL de autorización en la respuesta de MCP (o se imprimirá en la consola).
• Si no se proporciona user_google_email y las credenciales faltan o no son válidas , la herramienta mostrará un mensaje de error que indica al LLM que use la herramienta centralizada start_google_auth . El LLM debe entonces llamar start_google_auth con el correo electrónico del usuario y el service_name correspondiente (p. ej., "Google Calendar", "Google Docs", "Gmail", "Google Drive"). Esto también devolverá una URL de autorización.

Pasos para el Usuario (una vez obtenida una URL de autorización):

1. Abra la URL de autorización proporcionada en un navegador web.
2. Inicie sesión en la cuenta de Google y otorgue los permisos solicitados para el servicio especificado.
3. Después de la autorización, Google redirigirá el navegador a http://localhost:8000/oauth2callback (o a su URI de redirección configurada).
4. El servidor MCP maneja esta devolución de llamada, intercambia el código de autorización por tokens y almacena de forma segura las credenciales.
5. El LLM puede entonces reintentar la solicitud original. Las llamadas subsiguientes para el mismo usuario y servicio deberían funcionar sin necesidad de volver a autenticarse hasta que el token de actualización caduque o se revoque.

🧰 Herramientas disponibles

Nota : El primer uso de cualquier herramienta para un servicio específico de Google puede activar el flujo de autenticación OAuth si no se han almacenado credenciales válidas y se proporciona user_google_email a la herramienta. Si se requiere autenticación y no se proporciona user_google_email a la herramienta, el LLM debe usar la herramienta centralizada start_google_auth (definida en core/server.py ) con el correo electrónico del usuario y el service_name correspondiente.

📅 Calendario de Google

Fuente: gcalendar/calendar_tools.py

Todas las herramientas de Calendario admiten la autenticación mediante la sesión MCP actual ( mcp_session_id ) o como alternativa a user_google_email . Si ninguna de las dos está disponible y se requiere autenticación, la herramienta devolverá un error que indica al LLM que utilice la herramienta centralizada start_google_auth con el correo electrónico del usuario y service_name="Google Calendar" .

🕒 Parámetros de fecha/hora: Las herramientas aceptan tanto marcas de tiempo RFC3339 completas (p. ej., 2024-05-12T10:00:00Z) como fechas simples (p. ej., 2024-05-12). El servidor las formatea automáticamente según sea necesario.

📁 Google Drive

Fuente: gdrive/drive_tools.py

Sintaxis de consulta : para consultas de búsqueda de Google Drive, consulte Sintaxis de consulta de búsqueda de Drive

📧 Gmail

Fuente: gmail/gmail_tools.py

Sintaxis de consulta : para consultas de búsqueda de Gmail, consulte Sintaxis de consulta de búsqueda de Gmail

📝 Documentos de Google

Fuente: gdocs/docs_tools.py

🛠️ Desarrollo

Estructura del proyecto

Manejo de puertos para OAuth

El servidor maneja inteligentemente la URI de redirección OAuth 2.0 ( /oauth2callback ) sin necesidad de un marco de servidor web independiente:

• Utiliza las capacidades del servidor HTTP integradas de la biblioteca MCP subyacente cuando se ejecuta en modo HTTP o mediante mcpo
• Se registra una ruta MCP personalizada específicamente para /oauth2callback en el puerto 8000
• Cuando Google redirige al usuario nuevamente después de la autorización, el servidor MCP intercepta la solicitud en esta ruta.
• El módulo auth extrae el código de autorización y completa el intercambio de tokens.
• Esto requiere que OAUTHLIB_INSECURE_TRANSPORT=1 se configure cuando se ejecuta localmente, ya que la devolución de llamada utiliza http://localhost

Depuración

Consulte mcp_server_debug.log para obtener registros detallados, incluyendo los pasos de autenticación y las llamadas a la API. Habilite el registro de depuración si es necesario.

• Verifique que client_secret.json sea correcto y esté presente
• Asegúrese de que la URI de redireccionamiento correcta ( http://localhost:8000/oauth2callback ) esté configurada en Google Cloud Console
• Confirme que las API necesarias (Calendario, Drive, Gmail) estén habilitadas en su proyecto de Google Cloud
• Compruebe que OAUTHLIB_INSECURE_TRANSPORT=1 esté configurado en el entorno donde se ejecuta el proceso del servidor
• Busque mensajes de error específicos durante el flujo OAuth basado en navegador

Consulte los registros del servidor para ver si hay seguimientos o mensajes de error devueltos por las API de Google.

Agregar nuevas herramientas

1. Elija o cree el módulo apropiado (por ejemplo, gdocs/gdocs_tools.py )
2. Importar las bibliotecas necesarias (biblioteca cliente de la API de Google, etc.)
3. Define una función async para la lógica de tu herramienta. Usa sugerencias de tipo para los parámetros.
4. Decore la función con @server.tool("your_tool_name")
5. Dentro de la función, obtenga las credenciales autenticadas:

6. Cree el cliente del servicio API de Google: service = build('drive', 'v3', credentials=credentials)
7. Implementar la lógica para llamar a la API de Google
8. Manejar los posibles errores con elegancia
9. Devuelve los resultados como un diccionario o lista serializable en JSON
10. Importe la función de la herramienta en main.py para que se registre en el servidor
11. Defina las constantes de alcance específicas del servicio necesarias en el módulo de su herramienta
12. Actualice pyproject.toml si se requieren nuevas dependencias

Gestión de Ámbitos : La lista global SCOPES en config/google_config.py se utiliza para la pantalla inicial de consentimiento de OAuth. Cada herramienta debe solicitar los required_scopes mínimos necesarios al llamar get_credentials .

🔒 Notas de seguridad

• client_secret.json : Este archivo contiene credenciales confidenciales. NUNCA lo envíe al control de versiones. Asegúrese de que aparezca en su archivo .gitignore . Guárdelo de forma segura.
• Tokens de usuario : Las credenciales de usuario autenticadas (tokens de actualización) se almacenan localmente en archivos como credentials-<user_id_hash>.json . Proteja estos archivos, ya que otorgan acceso a los datos de la cuenta de Google del usuario. Asegúrese de que también estén en .gitignore .
• Seguridad de devolución de llamada de OAuth : El uso de http://localhost para la devolución de llamada de OAuth es estándar para las aplicaciones instaladas durante el desarrollo, pero requiere OAUTHLIB_INSECURE_TRANSPORT=1 . Para implementaciones de producción fuera de localhost, DEBE usar HTTPS para la URI de devolución de llamada y configurarla como corresponda en Google Cloud Console.
• Seguridad mcpo : si utiliza mcpo para exponer el servidor a través de la red, considere lo siguiente:
  • Uso de la opción --api-key para la autenticación básica
  • Ejecutar mcpo detrás de un proxy inverso (como Nginx o Caddy) para gestionar la terminación HTTPS, el registro adecuado y una autenticación más robusta
  • Vincular mcpo solo a interfaces de red confiables si se expone más allá del host local
• Gestión de ámbitos : El servidor solicita ámbitos OAuth (permisos) específicos para Calendario, Drive y Gmail. Los usuarios otorgan acceso según estos ámbitos durante la autenticación inicial. No solicite ámbitos más amplios de los necesarios para las herramientas implementadas.

Capturas de pantalla:

📄 Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo LICENSE para obtener más detalles.