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, Meet y Contacts — 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 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 — y la People API para contactos, que es como Google la llama en la consola)
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 vida útil.)

📦 → 🤖 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/`. Dale una carpeta dedicada — no tu carpeta personal, 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 el 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 · Docs<br>Sheets · Tasks · Meet · Contacts"]

    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 requiera registro. 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

12 herramientas en 8 servicios de Google, además de manejo multi-cuenta, acceso de solo lectura por cuenta, ejecución por lotes, creación de contenido y un sandbox de archivos.

Herramienta	Qué hace
`manage_email`	Gmail — buscar, leer (HTML plano 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 — crear y configurar espacios de reunión, ver quién está en una llamada ahora, explorar conferencias pasadas, participantes, transcripciones, grabaciones, notas inteligentes
`manage_contacts`	Contacts — buscar personas en tus contactos guardados, las direcciones con las que solo has mantenido correspondencia y el directorio de tu organización; crear, actualizar y eliminar contactos
`manage_accounts`	Ciclo de vida multi-cuenta — 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)
`bulk_operations`	Hacer muchas cosas en una sola llamada — encadenar diferentes operaciones en secuencia con referencias `$N.field`, o aplicar una operación a muchos recursos en una sola solicitud de Google (`queue_operations` sigue funcionando como alias)

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 puede encadenarlas.

Pides una 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 bulk_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.

Cuando el trabajo es la misma operación sobre muchas cosas, puede ir más allá y usar una sola solicitud de Google para todas:

bulk_operations { mode: 'batch', tool: 'manage_email', operation: 'trash',
                  items: ['msg1', 'msg2', 'msg3', … ] }

Doscientos mensajes a la papelera en un solo viaje de ida y vuelta en lugar de doscientos. Esto es deliberadamente limitado — funciona solo donde Google publica un método para ello, que hoy es contactos (crear, actualizar, eliminar, obtener) y Gmail (papelera, cambios de etiquetas). Pídelo en cualquier otro lugar y la respuesta nombra las operaciones que sí pueden, y te devuelve al modo secuencial, que funciona en todas partes.

Pide lo que falta

Este servidor expone 95 operaciones, alcanzando 79 de los 257 métodos que Google publica en esas ocho 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 257 operaciones no es más capaz que una con 95 — 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 tres APIs completas que este servidor aún no toca — Chat, Slides y Forms — por la misma razón: no 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. "Expón 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.

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 ello 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 patentes junto con su código, así que usarlo no puede convertirse en un problema de patentes más adelante. MIT es silencioso 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 de permitidos corporativas. Hazle 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" }

Da a una cuenta acceso de solo lectura

Algunas cuentas nunca deberían recibir escrituras. Pide menos en el momento del consentimiento y el token en sí no puede enviar, editar ni eliminar — esto no es una regla superpuesta a un token amplio:

manage_accounts { "operation": "scopes", "email": "you@gmail.com",
                  "services": "gmail,drive,contacts", "access": "read" }

A Google se le pide la variante de solo lectura de cada ámbito, así que marcar todas las casillas en la pantalla de consentimiento aún produce un token de solo lectura. manage_accounts status informa qué tiene realmente cada cuenta.

Una escritura desde una cuenta de solo lectura se rechaza antes de que la solicitud salga, con la cuenta, la operación y el camino de regreso:

'create' needs write access to contacts. Account you@gmail.com was authorized
read-only for contacts. Re-authorize with manage_accounts {operation:'scopes',
email:'you@gmail.com', services:'contacts', access:'readwrite'}, or use an
account that already has it.

Cuando un servicio no tiene ámbito de solo lectura, se te dice cuáles son y qué podrán hacer aún antes de que se abra el navegador.

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" }}
  ]
}

Una operación, muchas cosas

Donde Google publica un método para ello, la misma operación en muchos recursos cuesta una solicitud:

{
  "mode": "batch",
  "tool": "manage_contacts",
  "operation": "delete",
  "email": "you@gmail.com",
  "items": ["people/c1", "people/c2", "people/c3"]
}

Cualquier cosa compartida por todo el lote va en el nivel superior; items llevan solo lo que difiere — un id simple es suficiente cuando eso es todo.

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 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 tres APIs que aún no dirigimos
Decisiones de arquitectura — los ADRs, incluyendo por qué este servidor posee su cliente de Google por completo

Licencia

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