Servidor de Google Workspace de MCP

Un servidor de Protocolo de Contexto de Modelo para los servicios de Google Workspace. Este servidor proporciona herramientas para interactuar con Gmail y Google Calendar mediante el protocolo MCP.

Características

• Compatibilidad con varias cuentas de Google

  • Usar y cambiar entre varias cuentas de Google

  • Cada cuenta puede tener metadatos y descripciones personalizados.

• Integración con Gmail

  • Consultar correos electrónicos con búsqueda avanzada

  • Leer el contenido completo del correo electrónico y los archivos adjuntos

  • Crear y gestionar borradores

  • Responder correos electrónicos

  • Archivar correos electrónicos

  • Manejar accesorios

  • Soporte de operaciones masivas

• Integración de calendario

  • Lista de calendarios disponibles

  • Ver eventos del calendario

  • Crear nuevos eventos

  • Eliminar eventos

  • Soporte para múltiples calendarios

  • Compatibilidad con zonas horarias personalizadas

Ejemplos de indicaciones

Pruebe estos ejemplos de indicaciones con su asistente de IA:

Gmail

• "Recuperar mis últimos mensajes no leídos"

• "Buscar mis correos electrónicos del Scrum Master"

• Recuperar todos los correos electrónicos de contabilidad

• "Toma el correo electrónico sobre ABC y resúmelo"

• Escribe una buena respuesta al último correo electrónico de Alice y sube un borrador.

• Responder al correo electrónico de Bob con una nota de agradecimiento. Guardar como borrador.

Calendario

• "¿Qué tengo en mi agenda mañana?"

• Consulta la agenda familiar de mi cuenta privada para la próxima semana.

• Necesito organizar un evento con Tim de dos horas la semana que viene. ¿Podrías sugerirme algunos horarios?

Prerrequisitos

• Node.js >= 18

• Un proyecto de Google Cloud con las API de Gmail y Calendario habilitadas

• Credenciales OAuth 2.0 para las API de Google

Instalación

1. Clonar el repositorio:

   git clone https://github.com/j3k0/mcp-google-workspace.git cd mcp-google-workspace

2. Instalar dependencias:

   npm install

3. Construya el código TypeScript:

   npm run build

Configuración

Configuración de OAuth 2.0

Las API de Google Workspace (G Suite) requieren autorización OAuth2. Siga estos pasos para configurar la autenticación:

1. Crear credenciales OAuth2:

   • Vaya a la consola de Google Cloud

   • Crea un nuevo proyecto o selecciona uno existente

   • Habilite la API de Gmail y la API de Google Calendar para su proyecto

   • Vaya a "Credenciales" → "Crear credenciales" → "ID de cliente OAuth".

   • Seleccione "Aplicación de escritorio" o "Aplicación web" como tipo de aplicación.

   • Configurar la pantalla de consentimiento de OAuth con la información requerida

   • Agregar URI de redireccionamiento autorizados (incluya http://localhost:4100/code para desarrollo local)

2. Ámbitos OAuth2 requeridos:

   [ "openid", "https://mail.google.com/", "https://www.googleapis.com/auth/calendar", "https://www.googleapis.com/auth/userinfo.email" ]

3. Crea un archivo .gauth.json en la raíz del proyecto con tus credenciales de Google OAuth 2.0:

   { "installed": { "client_id": "your_client_id", "project_id": "your_project_id", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_secret": "your_client_secret", "redirect_uris": ["http://localhost:4100/code"] } }

4. Cree un archivo .accounts.json para especificar qué cuentas de Google pueden usar el servidor:

   { "accounts": [ { "email": "your.email@gmail.com", "account_type": "personal", "extra_info": "Primary account with Family Calendar" } ] }

   Puedes especificar varias cuentas. Asegúrate de que tengan acceso a tu aplicación de Google Auth. El campo extra_info es especialmente útil, ya que puedes añadir aquí información que quieras compartir con la IA sobre la cuenta (por ejemplo, si tiene un calendario específico).

Configuración del escritorio de Claude

Configurar Claude Desktop para utilizar el servidor mcp-google-workspace:

En MacOS: Edite ~/Library/Application\ Support/Claude/claude_desktop_config.json

En Windows: edite %APPDATA%/Claude/claude_desktop_config.json

Uso

1. Iniciar el servidor:

   npm start

   Argumentos opcionales:

   • --gauth-file : Ruta al archivo de credenciales de OAuth2 (predeterminado: ./.gauth.json)

   • --accounts-file : Ruta al archivo de configuración de cuentas (predeterminado: ./.accounts.json)

   • --credentials-dir : Directorio para almacenar las credenciales de OAuth (predeterminado: directorio actual)

2. El servidor se iniciará y escuchará los comandos MCP a través de stdin/stdout.

3. En la primera ejecución de cada cuenta, hará lo siguiente:

   • Abra una ventana del navegador para la autenticación OAuth2

   • Escuche en el puerto 4100 la devolución de llamada OAuth2

   • Almacene las credenciales para uso futuro en un archivo llamado .oauth2.{email}.json

Herramientas disponibles

Gestión de cuentas

1. gmail_list_accounts / calendar_list_accounts

   • Listar todas las cuentas de Google configuradas

   • Ver metadatos y descripciones de la cuenta

   • No se requiere user_id

Herramientas de Gmail

1. gmail_query_emails

   • Buscar correos electrónicos con la sintaxis de consulta de Gmail (por ejemplo, 'is:unread', 'from: example@gmail.com ', 'newer_than:2d', 'has:attachment')

   • Devuelve correos electrónicos en orden cronológico inverso

   • Incluye metadatos y resumen de contenido.

2. gmail_get_email

   • Recuperar el contenido completo del correo electrónico por ID

   • Incluye el cuerpo completo del mensaje y la información del archivo adjunto.

3. gmail_bulk_get_emails

   • Recuperar varios correos electrónicos por ID en una sola solicitud

   • Eficiente para el procesamiento por lotes

4. gmail_create_draft

   • Crear nuevos borradores de correo electrónico

   • Soporte para destinatarios de CC

5. gmail_delete_draft

   • Eliminar borradores de correos electrónicos por ID

6. gmail_reply

   • Responder a correos electrónicos existentes

   • Opción de enviar inmediatamente o guardar como borrador

   • Compatibilidad con "Responder a todos" mediante CC

7. gmail_get_attachment

   • Descargar archivos adjuntos de correo electrónico

   • Guardar en el disco o devolver como recurso incrustado

8. gmail_bulk_save_attachments

   • Guarde varios archivos adjuntos en una sola operación

9. gmail_archive / gmail_bulk_archive

   • Mover correos electrónicos fuera de la bandeja de entrada

   • Soporte para operaciones individuales o masivas

Herramientas de calendario

1. calendar_list

   • Listar todos los calendarios accesibles

   • Incluye metadatos de calendario, roles de acceso e información de zona horaria.

2. calendar_get_events

   • Recuperar eventos en un rango de fechas

   • Soporte para múltiples calendarios

   • Opciones de filtro (eventos eliminados, resultados máximos)

   • Personalización de la zona horaria

3. calendar_create_event

   • Crear nuevos eventos de calendario

   • Soporte para asistentes y notificaciones

   • Campos de ubicación y descripción

   • Manejo de zonas horarias

4. calendar_delete_event

   • Eliminar eventos por ID

   • Opción para notificaciones de cancelación

Desarrollo

• El código fuente está en TypeScript en el directorio src/

• La salida de la compilación va al directorio dist/

• Utiliza módulos ES para una mejor modularidad

• Sigue las mejores prácticas de la API de Google

Estructura del proyecto

Comandos de desarrollo

• npm run build : compila código TypeScript

• npm start : Inicia el servidor

• npm run dev : Iniciar en modo de desarrollo con recarga automática

Contribuyendo

1. Bifurcar el repositorio

2. Crear una rama de características

3. Confirme sus cambios

4. Empujar hacia la rama

5. Crear una solicitud de extracción

Licencia

Licencia MIT: consulte el archivo de LICENCIA para obtener más detalles