gworkspace-mcp

Servidor del Protocolo de Contexto de Modelo (MCP) para la automatización de Google Workspace: Google Sheets, Apps Script, Drive, Docs, Gmail y disparadores. Construido con FastMCP.

Diseñado para ser utilizado desde Claude Code (o cualquier cliente compatible con MCP) para que puedas editar proyectos de Apps Script, manipular hojas de cálculo, enviar correos electrónicos y gestionar archivos de Drive directamente desde una conversación.

Características

• Apps Script (9 herramientas) — listar, leer, actualizar, crear, desplegar y ejecutar proyectos de Apps Script. Ediciones de archivos granulares para que no tengas que reescribir scripts completos.

• Sheets (10 herramientas) — leer/escribir rangos, actualizaciones por lotes, formato, protección, fórmulas, paneles.

• Drive (4 herramientas) — listar, buscar, mover y gestionar archivos.

• Docs (1 herramienta) — leer/editar documentos de Google Docs.

• Gmail (3 herramientas) — redactar y enviar correos electrónicos.

• Triggers (3 herramientas) — gestionar disparadores de Apps Script basados en tiempo y eventos.

• Connect (1 herramienta) — vincular un proyecto local de Apps Script a una hoja de cálculo.

Requisitos

• Python 3.10+

• Un proyecto de Google Cloud con las siguientes API habilitadas:

  • Google Sheets API

  • Google Drive API

  • Apps Script API

  • Google Docs API

  • Gmail API

  • Google Calendar API

• Credenciales de escritorio OAuth 2.0 (client_secret.json)

Instalación

git clone https://github.com/LeooNic/gworkspace-mcp.git
cd gworkspace-mcp
pip install -e .

O con uv:

uv pip install -e .

Configuración de Google Cloud

1. Ve a console.cloud.google.com y crea un proyecto.

2. Habilita las API enumeradas anteriormente en API y servicios → Biblioteca.

3. Ve a API y servicios → Pantalla de consentimiento de OAuth, configúrala como Externa y añade tu cuenta de Google como usuario de prueba.

4. Ve a API y servicios → Credenciales → Crear credenciales → ID de cliente de OAuth, elige App de escritorio y descarga el JSON.

5. Haz que las credenciales estén disponibles para el servidor de una de estas formas:

   • Coloca el JSON en ~/.secrets/gworkspace-mcp/client_secret.json, o

   • Establece GOOGLE_CLIENT_SECRET_PATH=/ruta/completa/a/client_secret.json, o

   • Establece GOOGLE_OAUTH_CLIENT_ID y GOOGLE_OAUTH_CLIENT_SECRET como variables de entorno.

La primera vez que se ejecuta una herramienta, se abrirá una ventana del navegador para el consentimiento de OAuth. El token resultante se almacena en ~/.secrets/gworkspace-mcp/token.json y se actualiza automáticamente.

Registrar con Claude Code

Añade esto a tu settings.json de Claude Code (o ~/.claude.json):

{
  "mcpServers": {
    "gworkspace": {
      "command": "gworkspace-mcp"
    }
  }
}

Si gworkspace-mcp no está en tu PATH, utiliza la ruta absoluta al ejecutable creado por pip install -e . (en Windows, normalmente C:\Users\<usuario>\AppData\Local\Programs\Python\Python3XX\Scripts\gworkspace-mcp.exe).

Invocación alternativa sin instalar el punto de entrada:

{
  "mcpServers": {
    "gworkspace": {
      "command": "python",
      "args": ["-m", "gworkspace_mcp.server"]
    }
  }
}

Alcances (scopes) de OAuth

El servidor solicita los siguientes alcances:

• spreadsheets, drive, documents, calendar

• script.projects, script.deployments, script.processes, script.metrics

• gmail.send, gmail.compose

• userinfo.email, userinfo.profile

Notas de seguridad

• Tu client_secret.json y token.json son personales; nunca los subas a un repositorio. El .gitignore del repositorio ya los excluye.

• Los tokens viven en ~/.secrets/gworkspace-mcp/.

• El servidor se ejecuta localmente; no expone ningún punto final de red.

Licencia

MIT — ver LICENSE.