Google Workspace

Gestiona Gmail, Calendar, Drive y Contactos a través de las APIs de Google Workspace usando OAuth 2.0.

Documentación

Servidor MCP de Google Workspace

Dale a tu agente de IA acceso real a Google Workspace — Gmail, Calendar, Drive, Docs, Sheets, Tasks y Meet — desde un solo servidor MCP, en tantas cuentas como tengas.

Busca en tu correo, revisa tu calendario, escribe un documento, crea una tarea — en conversación, como tú mismo.

Instalación

Primero, necesitas credenciales OAuth de Google — el único requisito previo común a todas las vías:

Ve a console.cloud.google.com/apis/credentials
Crea un ID de cliente OAuth 2.0, tipo de aplicación Aplicación de escritorio
Habilita las APIs que quieras (Gmail, Calendar, Drive, Sheets, Docs, Tasks, Meet)
Ten a mano el ID de cliente y el Secreto de cliente — los pegarás a continuación

Luego elige la vía que coincida con cómo trabajas. Las tres ejecutan el mismo servidor.

Node 22.12 o más reciente. (Node 18 y 20 están ambos al final de su ciclo de vida).

📦 → 🤖 Claude Desktop — instalación de un clic con `.mcpb` (recomendado)

Descarga google-workspace-mcp.mcpb desde la última versión, luego arrástralo sobre la ventana de Claude Desktop, o haz doble clic en él.

Claude Desktop abre un diálogo de instalación con tres campos:

Campo
ID de cliente OAuth de Google	obligatorio — del paso anterior
Secreto de cliente OAuth de Google	obligatorio — del paso anterior
Directorio de trabajo	opcional — donde aterrizan adjuntos, descargas y exportaciones. El valor predeterminado es `~/.local/share/google-workspace-mcp/workspace/`. Asígnale una carpeta dedicada — no tu carpeta de inicio, Documentos, Escritorio ni una carpeta de Google Drive.

Pega, guarda, listo. Sin JSON que editar, sin Node que instalar, sin rutas que acertar — el paquete incluye el servidor y todas las dependencias.

Un solo paquete cubre todas las plataformas — macOS (Intel y Apple Silicon), Linux (x64 y ARM64) y Windows. No hay nada que elegir: el servidor es JavaScript puro, así que no hay carga específica por plataforma entre la que escoger.

Nota multiplataforma: los archivos .mcpb se instalan mediante el manejador integrado de Claude Desktop. Si hacer doble clic no activa Claude en tu sistema, arrastra el archivo sobre la ventana de Claude Desktop en su lugar, o haz clic derecho → "Abrir con…" y elige Claude Desktop (luego "abrir siempre con" si tu sistema operativo lo ofrece). El comportamiento varía: macOS normalmente asocia automáticamente, Windows puede necesitar una asociación única, Linux varía según el entorno de escritorio.

Claude Code — un solo comando

claude mcp add google-workspace \
  -e GOOGLE_CLIENT_ID=your-client-id \
  -e GOOGLE_CLIENT_SECRET=your-client-secret \
  -- npx -y @aaronsb/google-workspace-mcp

Eso es todo — sin archivos que editar. Verifica con /mcp.

Otros clientes MCP

Añade una entrada al archivo de configuración MCP del cliente (para Claude Desktop a mano, eso es claude_desktop_config.json; para Claude Code, .mcp.json):

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "@aaronsb/google-workspace-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

O instálalo globalmente y apunta al binario directamente:

npm install -g @aaronsb/google-workspace-mcp

Cómo encaja todo

flowchart LR
    human["🧑 You<br>ask in plain language"]
    agent["🤖 Your AI agent<br>Claude Desktop, Claude Code…"]
    server["⚙️ This MCP server<br>picks the right account,<br>builds the real request"]
    keys[("🔑 Your accounts<br>OAuth tokens, kept<br>on your own machine")]
    google["☁️ Google<br>Gmail · Calendar · Drive<br>Docs · Sheets · Tasks · Meet"]

    human -->|"“what's on my calendar?”"| agent
    agent -->|"tool call"| server
    server <-->|"which account?"| keys
    server -->|"real API call, as you"| google
    google -->|"your data"| server
    server -->|"shaped for an agent<br>+ what to do next"| agent
    agent -->|"an answer"| human

    classDef person   fill:#475569,color:#ffffff,stroke:#94a3b8
    classDef robot    fill:#2d7d9a,color:#ffffff,stroke:#4a5568
    classDef ours     fill:#7c3aed,color:#ffffff,stroke:#8b5cf6
    classDef secrets  fill:#2d8e5e,color:#ffffff,stroke:#4a5568
    classDef external fill:#f6821f,color:#1a1a1a,stroke:#d97706

    class human person
    class agent robot
    class server ours
    class keys secrets
    class google external

Tus credenciales nunca salen de tu máquina. El servidor guarda un token OAuth por cuenta, en tu propio disco, y llama a Google como tú — no hay servicio intermediario, ni cuenta nuestra, ni nada que registrar. Añade tantas cuentas como quieras (personal y de trabajo, lado a lado); el servidor enruta cada solicitud a la correcta.

Lo que puede hacer

11 herramientas en 7 servicios de Google, más manejo de múltiples cuentas, procesamiento por lotes, creación de contenido y un sandbox de archivos.

Herramienta	Qué hace
`manage_email`	Gmail — buscar, leer (HTML simple o saneado), enviar, responder / responder a todos, reenviar, clasificar, papelera, etiquetas, hilos, adjuntos
`manage_calendar`	Calendar — listar, agenda, obtener, crear, quickAdd (lenguaje natural), actualizar, eliminar, calendarios, freebusy
`manage_drive`	Drive — buscar, obtener, subir, descargar, copiar, renombrar / mover, eliminar, exportar, permisos, comentarios, ver imágenes
`manage_sheets`	Sheets — leer / escribir rangos (salida numerada por filas), añadir, limpiar, gestionar pestañas, copiar / duplicar / renombrar
`manage_docs`	Docs — obtener, crear, añadir, insertar texto, buscar y reemplazar
`manage_tasks`	Tasks — listar / crear / actualizar / completar tareas y listas de tareas
`manage_meet`	Meet — explorar conferencias pasadas, participantes, transcripciones, grabaciones, notas inteligentes
`manage_accounts`	Ciclo de vida de múltiples cuentas — añadir cuentas, gestionar credenciales y ámbitos
`manage_scratchpad`	Redactar / editar contenido multilínea (direccionado por línea o ruta JSON), adjuntar archivos, enviar a cualquier destino; el modo JSON sincroniza en vivo con Docs / Sheets
`manage_workspace`	Operaciones de archivos en el sandbox del espacio de trabajo (punto de intercambio para adjuntos, descargas, exportaciones)
`queue_operations`	Encadenar operaciones secuencialmente con referencias de resultados `$N.field`

Cada respuesta incluye orientación de próximos pasos, para que el agente siempre sepa qué puede hacer después.

Una petición, muchos pasos

La parte útil no es ninguna operación individual — es que tu agente pueda encadenarlas.

Pides una sola cosa. El agente deduce que necesita cuatro llamadas a la API, en orden, cada una alimentando a la siguiente:

sequenceDiagram
    autonumber
    participant H as 🧑 You
    participant A as 🤖 Your agent
    participant S as ⚙️ MCP server
    participant G as ☁️ Google

    H->>A: "file the invoice from Acme<br>and remind me to pay it Friday"
    A->>S: find the email
    S->>G: search Gmail
    G-->>S: the message
    S-->>A: found it — and here's what you can do next
    A->>S: save the attachment
    S->>G: download it
    A->>S: put it in Drive
    S->>G: upload
    A->>S: create a task, due Friday
    S->>G: Google Tasks
    A-->>H: Done. Invoice filed, task set for Friday.

Dos cosas hacen que esto funcione. Cada respuesta le dice al agente qué puede hacer después, para que no adivine el siguiente paso. Y queue_operations le permite ejecutar toda una cadena en una sola llamada, alimentando cada resultado en la siguiente — así que "encuentra la factura, archívala, recuérdamelo" es un solo viaje de ida y vuelta en lugar de cuatro.

Pide lo que falta

Este servidor expone 80 operaciones, alcanzando 60 de los 233 métodos que Google publica en esas siete APIs. Es un subconjunto curado a propósito: un agente tiene que elegir entre estos, y cada método que debe sopesar es uno que puede elegir mal. Una herramienta con 233 operaciones no es más capaz que una con 80 — es más difícil de usar correctamente.

Pero ese juicio se hizo sin ti.

→ Explora cada método que Google publica

Cada método está listado — qué hace, si lo exponemos, y un enlace de Solicitud que abre un issue prellenado. Las descripciones son las propias de Google, citadas textualmente, y la página se genera a partir de la misma especificación con la que se construye el cliente, así que no puede desviarse de la realidad.

Esa página también lista cuatro APIs completas que este servidor aún no toca — Chat, Contacts, Slides y Forms — por la misma razón: no estar dirigido es una decisión, no un hecho de la naturaleza.

Una buena solicitud nombra la tarea, no el método:

"Quiero que el agente archive automáticamente las facturas entrantes en una carpeta."

Eso se puede evaluar. Podría resultar que una operación existente ya lo hace, o que la respuesta correcta sea un método diferente al que encontraste. "Exponer users.settings.filters.create" es una conclusión, no un caso — lidera con el problema y deja que el método siga.

Por qué Apache 2.0, y no open core

Todo está aquí. No hay nivel de pago, ni versión "empresarial", ni función retenida para vendértela después. Lo que instalas es lo que existe.

El open core funciona reteniendo la parte buena. Lo gratuito es un imán de clientes, y en el momento en que tu uso se vuelve serio descubres que la operación que necesitas vive detrás de una licencia. Ese modelo sería especialmente malo aquí: esto es una pieza de plomería entre tú y tus propios datos, usando tus propias credenciales de Google, ejecutándose en tu propia máquina. Nada de ese arreglo debería tener un muro de pago en medio, y nada de él necesita un proveedor.

Apache 2.0 en lugar de MIT por dos razones concretas:

Una concesión explícita de patentes. Los contribuyentes licencian sus reclamaciones de patente junto con su código, así que usar esto no puede convertirse en un problema de patentes más adelante. MIT guarda silencio sobre patentes, lo que significa que la pregunta simplemente queda sin respuesta en lugar de resuelta.
Es seguro adoptarlo en el trabajo. Apache 2.0 está esencialmente en todas las listas blancas corporativas. Haz un fork, intégralo, envíalo dentro de un producto comercial — no le debes nada a nadie, y no necesitas pedir permiso.

La única obligación es la atribución: mantén los avisos (NOTICE, LICENSE) con el código. Eso es todo.

Hasta la v3.0.0 este proyecto tenía licencia MIT, y esa historia se preserva en lugar de borrarse — las contribuciones de la era MIT conservan su aviso original en LICENSE-MIT, y sus autores reciben crédito en NOTICE. Apache 2.0 no quita nada de lo que MIT permitía.

Uso

Añade una cuenta (abre un navegador para OAuth):

manage_accounts { "operation": "authenticate" }

Luego usa cualquier herramienta con el correo de tu cuenta:

manage_email    { "operation": "triage", "email": "you@gmail.com" }
manage_calendar { "operation": "agenda", "email": "you@gmail.com" }
manage_drive    { "operation": "search", "email": "you@gmail.com", "query": "quarterly report" }

Flujos de trabajo de varios pasos

Encadena operaciones con referencias de resultados — la salida de un paso alimenta al siguiente:

{
  "operations": [
    { "tool": "manage_email", "args": { "operation": "search", "email": "you@gmail.com", "query": "from:boss subject:review" }},
    { "tool": "manage_email", "args": { "operation": "read", "email": "you@gmail.com", "messageId": "$0.messageId" }}
  ]
}

Dónde viven tus datos

Sigue la Especificación de Directorio Base XDG:

Datos	Ubicación
Registro de cuentas	`~/.config/google-workspace-mcp/accounts.json`
Credenciales	`~/.local/share/google-workspace-mcp/credentials/`
Espacio de trabajo (intercambio de archivos)	`~/.local/share/google-workspace-mcp/workspace/`

Las credenciales son archivos por cuenta que contienen tokens OAuth estándar. No se almacenan secretos en el directorio del proyecto.

Bajo el capó

No necesitas nada de esto para usar el servidor. Pero si tienes curiosidad, o quieres añadir una operación:

El servidor construye su cliente de API de Google a partir de las propias especificaciones de API legibles por máquina de Google. Nada se transcribe a mano, así que la superficie no puede desviarse de la realidad, y añadir una operación es una edición de YAML en lugar de un cambio de código.

Cómo funciona — la división tiempo de compilación / tiempo de ejecución, el descriptor, la fábrica
Cobertura de API — qué está expuesto, qué no, y cómo pedir más
La superficie completa de API — cada método que Google publica, más las cuatro APIs que aún no dirigimos
Decisiones de arquitectura — los ADR, incluyendo por qué este servidor es dueño de su cliente de Google por completo

Licencia

Licencia Apache 2.0 — ver Por qué Apache 2.0 arriba.