Ultimate Google Docs & Drive MCP Server

Servidor MCP de Google Docs, Sheets, Drive, Gmail y Calendar

Conecta Claude Desktop, Cursor o cualquier cliente MCP a tus Google Docs, Google Sheets, Google Drive, Gmail y Google Calendar.

---

Inicio Rápido

1. Crear un Cliente OAuth de Google Cloud

1. Ve a la Consola de Google Cloud
2. Crea o selecciona un proyecto
3. Habilita la API de Google Docs, la API de Google Sheets, la API de Google Drive, la API de Gmail y la API de Google Calendar
4. Configura la pantalla de consentimiento OAuth (Externa, agrega tu correo como usuario de prueba y añade los alcances gmail.modify y calendar.events junto con los alcances de Docs/Sheets/Drive)
5. Crea un ID de cliente OAuth (tipo aplicación de escritorio)
6. Copia el ID de cliente y el Secreto de cliente desde la pantalla de confirmación

¿Necesitas más detalles? Consulta las instrucciones paso a paso al final de esta página.

2. Autorizar

GOOGLE_CLIENT_ID="your-client-id" \
GOOGLE_CLIENT_SECRET="your-client-secret" \
npx -y @a-bonus/google-docs-mcp auth

Esto abre tu navegador para la autorización de Google. Después de que apruebes, el token de actualización se guarda en ~/.config/google-docs-mcp/token.json.

3. Agregar a tu Cliente MCP

Claude Desktop / Cursor / Windsurf:

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

El servidor se inicia automáticamente cuando tu cliente MCP lo necesita.

Implementación Remota (Cloud Run)

Implementa una vez para tu equipo: no se requieren instalaciones locales. El servidor usa MCP OAuth 2.1 para que tu cliente MCP maneje la autenticación automáticamente.

gcloud run deploy google-docs-mcp \
  --source . \
  --region europe-west3 \
  --port 8080 \
  --allow-unauthenticated \
  --set-env-vars "^|^MCP_TRANSPORT=httpStream|BASE_URL=https://your-service.run.app|GOOGLE_CLIENT_ID=...|GOOGLE_CLIENT_SECRET=...|TOKEN_STORE=firestore|JWT_SIGNING_KEY=your-secret-key"

Luego cada usuario solo agrega la URL a su cliente MCP: sin npx, sin tokens, sin configuración local:

{
  "mcpServers": {
    "google-docs": {
      "type": "streamableHttp",
      "url": "https://your-service.run.app/mcp"
    }
  }
}

Tu cliente MCP solicitará el inicio de sesión de Google en la primera conexión. Consulta Implementación Remota para más detalles.

---

¿Qué Puede Hacer?

Herramientas en Google Docs, Sheets y Drive:

Google Docs

Herramienta	Descripción
readDocument	Leer contenido como texto plano, JSON o markdown
appendText	Agregar texto a un documento
insertText	Insertar texto en una posición específica
deleteRange	Eliminar contenido por rango de índice
modifyText	Reemplazar, anteponer o transformar texto en un documento
findAndReplace	Buscar y reemplazar texto en un documento
findElement	Localizar ocurrencias de texto (con rangos de índice) o listar párrafos/tablas
listTabs	Listar todas las pestañas en un documento de múltiples pestañas
addTab	Agregar una nueva pestaña a un documento
renameTab	Renombrar una pestaña de documento
replaceDocumentWithMarkdown	Reemplazar todo el contenido del documento desde markdown
replaceRangeWithMarkdown	Reemplazar un rango específico con contenido markdown
appendMarkdown	Agregar contenido con formato markdown
applyTextStyle	Negrita, cursiva, colores, tamaño de fuente, enlaces
applyParagraphStyle	Alineación, espaciado, sangría
insertTable	Crear una tabla vacía
insertTableWithData	Crear una tabla prellenada con datos
insertPageBreak	Insertar saltos de página
insertSectionBreak	Insertar salto de sección (NEXT_PAGE o CONTINUOUS)
updateSectionStyle	Actualizar estilo de sección: cambiar orientación, márgenes
insertImage	Insertar imágenes desde URLs o archivos locales

Comentarios

Herramienta	Descripción
listComments	Ver todos los comentarios con autor y fecha
getComment	Obtener un comentario específico con respuestas
addComment	Crear un comentario anclado a texto
replyToComment	Responder a un comentario existente
resolveComment	Marcar un comentario como resuelto
deleteComment	Eliminar un comentario

Google Sheets

Herramienta	Descripción
readSpreadsheet	Leer datos de un rango (notación A1)
writeSpreadsheet	Escribir datos en un rango
batchWrite	Escribir en múltiples rangos en una sola llamada
appendRows	Agregar filas a una hoja
clearRange	Borrar valores de celdas
createSpreadsheet	Crear una nueva hoja de cálculo
addSheet	Agregar una hoja/pestaña
deleteSheet	Eliminar una hoja/pestaña
duplicateSheet	Duplicar una hoja dentro de la misma hoja de cálculo
copySheetTo	Copiar una hoja a otra hoja de cálculo
renameSheet	Renombrar una hoja/pestaña
getSpreadsheetInfo	Obtener metadatos y lista de hojas
listSpreadsheets	Buscar hojas de cálculo
formatCells	Negrita, colores, alineación, alineación vertical, estrategia de ajuste en rangos
copyFormatting	Copiar formato de un rango a otro
readCellFormat	Leer detalles de formato de un rango de celdas
setCellBorders	Establecer bordes por lado (superior/inferior/izquierdo/derecho/interno) con estilo y color
freezeRowsAndColumns	Fijar filas/columnas de encabezado
setDropdownValidation	Agregar/eliminar listas desplegables en celdas
setColumnWidths	Establecer anchos de columna en píxeles
setRowHeights	Establecer alturas de fila en píxeles
autoResizeColumns	Ajustar automáticamente el ancho de columnas al contenido
autoResizeRows	Ajustar automáticamente la altura de filas al contenido
protectRange	Bloquear un rango o toda la hoja (solo advertencia o bloqueo completo)
addConditionalFormatting	Agregar una regla de formato condicional
getConditionalFormatting	Listar reglas de formato condicional con su índice (JSON)
deleteConditionalFormatting	Eliminar reglas de formato condicional por índice
groupRows	Agrupar filas para secciones plegables
ungroupAllRows	Eliminar todos los agrupamientos de filas
createSheetsComment	Crear un comentario de hoja de cálculo, opcionalmente con enlace directo a celda
createSheetsCellNote	Crear una nota de celda nativa adjunta a una celda o rango
insertChart	Crear un gráfico a partir de datos
deleteChart	Eliminar un gráfico

Tablas de Google Sheets

Herramienta	Descripción
createTable	Crear una nueva tabla nombrada con tipos de columna
listTables	Listar todas las tablas en una hoja de cálculo o hoja
getTable	Obtener metadatos detallados de tabla por nombre o ID
deleteTable	Eliminar una tabla (opcionalmente borrar datos)
updateTableRange	Modificar dimensiones de tabla (agregar/eliminar filas/columnas)
appendTableRows	Agregar filas a una tabla (inserción consciente de tabla)

Google Drive

Herramienta	Descripción
listDocuments	Listar documentos, opcionalmente filtrados por fecha
searchDocuments	Buscar por nombre o contenido
getDocumentInfo	Obtener metadatos de documento
createDocument	Crear un nuevo documento
createDocumentFromTemplate	Crear desde una plantilla existente
createFolder	Crear una carpeta
listFolderContents	Listar contenido de carpeta
getFolderInfo	Obtener metadatos de carpeta
moveFile	Mover un archivo a otra carpeta
copyFile	Duplicar un archivo
renameFile	Renombrar un archivo
deleteFile	Mover a la papelera o eliminar permanentemente
listDriveFiles	Listar cualquier tipo de archivo en Drive con filtros
searchDriveFiles	Buscar todos los archivos de Drive por nombre o contenido
downloadFile	Descargar el contenido de un archivo

Gmail

Herramienta	Descripción
listMessages	Listar o buscar mensajes usando la sintaxis de consulta de Gmail (is:unread, from:, newer_than:, etc.)
getMessage	Obtener un solo mensaje con encabezados decodificados, cuerpo en texto plano, cuerpo HTML y metadatos de adjuntos
sendEmail	Enviar un correo en texto plano. Admite cc/cco y respuestas en hilo mediante replyToMessageId
trashMessage	Mover un mensaje a la Papelera (reversible, igual que hacer clic en Eliminar en la interfaz de Gmail)
modifyMessageLabels	Agregar o quitar etiquetas en un mensaje — úsalo para destacar, archivar (quitar INBOX), marcar como leído (quitar UNREAD)
listLabels	Listar todas las etiquetas del sistema y personalizadas con sus IDs
createDraft	Redactar un borrador en lugar de enviar de inmediato — para flujos de redacción/revisión/envío
listDrafts	Listar borradores existentes con destinatario, asunto y fragmento
getDraft	Obtener un solo borrador con encabezados y cuerpo completos
updateDraft	Reemplazar el contenido de un borrador existente (reemplazo completo, no un parche)
sendDraft	Enviar un borrador existente por ID
deleteDraft	Eliminar permanentemente un borrador (no se mueve a la Papelera — desaparece)
triageInbox	Compuesto: obtener mensajes no leídos con contenido + indicadores heurísticos (boletín, reunión, acción) para una clasificación de bandeja de entrada de una sola pasada

Google Calendar

Herramienta	Descripción
listEvents	Listar o buscar eventos con q, timeMin, timeMax, maxResults (por defecto usa el calendario principal)
createEvent	Crear un evento con título, inicio/fin, descripción, ubicación, asistentes, enlace opcional de Google Meet
updateEvent	Actualización estilo PATCH — solo cambian los campos que pases. Úsalo para reprogramar, cambiar título, modificar asistentes
deleteEvent	Eliminar permanentemente un evento. El sendUpdates opcional envía cancelaciones por correo a los asistentes
quickAddEvent	Creación de eventos en lenguaje natural: "Lunch with Sarah tomorrow 12pm" — Google analiza el resto

Apps Script

Automatiza la automatización: crea y edita el Apps Script detrás de un Documento u Hoja — onEdit disparadores, menús personalizados, trabajos programados — en lugar de decirle al usuario que pegue código en el editor manualmente.

Herramienta	Descripción
createAppsScriptProject	Crear un proyecto, opcionalmente vinculado a un Documento/Hoja/Presentación/Formulario mediante parentId, y escribir sus archivos iniciales en la misma llamada
getAppsScriptContent	Leer los archivos de un proyecto — pasa includeSource: false para un listado rápido, o versionNumber para leer una versión guardada
updateAppsScriptContent	Escribir archivos. merge (predeterminado) reemplaza archivos con el mismo nombre y conserva el resto; replace hace que el proyecto sea exactamente los archivos que pases

Requiere dos cosas además de la configuración habitual:

1. La API de Apps Script debe estar habilitada por cuenta de Google en https://script.google.com/home/usersettings — está desactivada por defecto, y un error 403 con "Apps Script API" en el mensaje significa que se omitió este paso.
2. El alcance script.projects, que está incluido en SCOPES. Las instalaciones existentes deben volver a autorizar una vez para incorporarlo.

---

Ejemplos de uso

Google Docs

"Read document ABC123 as markdown"
"Append 'Meeting notes for today' to document ABC123"
"Make the text 'Important' bold and red in document ABC123"
"Replace the entire document with this markdown: # Title\n\nNew content here"
"Insert a 3x4 table at index 50 in document ABC123"

Google Sheets

"Read range A1:D10 from spreadsheet XYZ789"
"Write [[Name, Score], [Alice, 95], [Bob, 87]] to range A1 in spreadsheet XYZ789"
"Create a new spreadsheet titled 'Q1 Report'"
"Format row 1 as bold with a light blue background in spreadsheet XYZ789"
"Freeze the first row in spreadsheet XYZ789"
"Add a dropdown with options [Open, In Progress, Done] to range C2:C100"
"Create a table named 'Tasks' in range A1:D10 with columns: Task (TEXT), Status (DROPDOWN: 'Not Started','In Progress','Done'), Priority (NUMBER)"
"Add a medium solid border around A1:D10 in spreadsheet XYZ789"
"Protect the header row so collaborators can't accidentally edit it"
"Auto-fit row heights for rows 2–50 after wrapping text"

Google Drive

"List my 10 most recent Google Docs"
"Search for documents containing 'project proposal'"
"Create a folder called 'Meeting Notes' and move document ABC123 into it"

Gmail

"Show me my 20 most recent unread emails"
"Search Gmail for messages from alice@example.com in the last 7 days"
"Read the full body of message ID 18c3f4a2b1d9"
"Send an email to bob@example.com with the subject 'Weekly update' and this body..."
"Reply to message 18c3f4a2b1d9 with 'Thanks, confirmed.'"
"Star message 18c3f4a2b1d9 and archive it"
"Move message 18c3f4a2b1d9 to Trash"
"List all my Gmail labels"
"Draft a reply to that email but don't send it yet — let me review first"
"Show me my drafts, then send the one to bob@"
"Triage my unread inbox: tell me which 20 emails need attention and which are noise"

Google Calendar

"What's on my calendar this week?"
"Create an event titled 'Project review' tomorrow from 2pm to 3pm Pacific time"
"Quick add: lunch with Alex Friday 12:30"
"Reschedule event abc123 to next Monday at 10am"
"Delete the 'Standup' event tomorrow"
"List all events on my calendar between April 15 and April 22"
"Schedule a 30-minute meeting with bob@example.com next Wednesday at 11am with a Google Meet link"

Flujo de trabajo con Markdown

El servidor admite un flujo de trabajo completo de ida y vuelta con markdown:

1. Leer un documento como markdown: readDocument con format='markdown'
2. Editar el markdown localmente
3. Enviar los cambios de vuelta: replaceDocumentWithMarkdown

Compatible con: encabezados, negrita, cursiva, tachado, enlaces, listas con viñetas/numeradas, reglas horizontales.

Verificación en vivo de documentos

El repositorio incluye una prueba de integración en vivo opcional para cloneTable contra la API real de Google Docs. Está omitida por defecto.

Requisitos:

• GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET válidos
• un token autorizado ya almacenado mediante npx -y @a-bonus/google-docs-mcp auth

Ejecútala con:

GOOGLE_DOCS_LIVE_TESTS=1 npm run test:live:docs

Esta prueba crea documentos de Google de origen/destino temporales, verifica cloneTable y luego elimina los archivos de prueba.

---

Implementación remota

Implementa el servidor de forma centralizada en Google Cloud Run (o cualquier host de contenedores) para que tu equipo pueda usarlo sin instalaciones locales. El servidor usa MCP OAuth 2.1 con el GoogleProvider integrado de FastMCP — los clientes MCP manejan el flujo de autenticación automáticamente.

Visita la URL raíz del servidor (/) para obtener instrucciones de configuración y una configuración de cliente lista para copiar.

Variables de entorno

Variable	Descripción
MCP_TRANSPORT	Establécelo en httpStream para habilitar el modo remoto (predeterminado: stdio)
BASE_URL	URL pública del servidor implementado (requerida para redirecciones de OAuth)
GOOGLE_CLIENT_ID	ID de cliente de OAuth (tipo aplicación web)
GOOGLE_CLIENT_SECRET	Secreto del cliente de OAuth
MCP_TOOL_GROUPS	Grupos de herramientas opcionales separados por comas para registrar: docs, drive, sheets, utils, gmail, calendar, script o all
ALLOWED_DOMAINS	Lista separada por comas de dominios permitidos de Google Workspace (opcional)
PORT	Puerto HTTP (predeterminado: 8080)
TOKEN_STORE	Establécelo en firestore para almacenamiento persistente de tokens (predeterminado: en memoria)
JWT_SIGNING_KEY	Clave de firma fija para que los tokens sobrevivan a los reinicios (se genera automáticamente si no se establece)
REFRESH_TOKEN_TTL	Vida útil del token de actualización en segundos (predeterminado: 2592000 / 30 días)
GCLOUD_PROJECT	ID del proyecto de GCP para Firestore (requerido cuando TOKEN_STORE=firestore)
MCP_STATELESS	Establécelo en true para implementaciones sin servidor (Cloud Run, etc.) — desactiva el seguimiento de sesiones para sobrevivir al escalado a cero

Configuración

1. Crea un proyecto de GCP y habilita las API de Docs, Sheets y Drive
2. Crea un cliente de OAuth (tipo aplicación web, no de escritorio)
3. Establece la URI de redirección autorizada en {BASE_URL}/oauth/callback
4. Implementa en Cloud Run:

gcloud run deploy google-docs-mcp \
  --source . \
  --region europe-west3 \
  --port 8080 \
  --allow-unauthenticated \
  --set-env-vars "^|^MCP_TRANSPORT=httpStream|BASE_URL=https://your-service.run.app|ALLOWED_DOMAINS=yourdomain.com|GOOGLE_CLIENT_ID=...|GOOGLE_CLIENT_SECRET=...|TOKEN_STORE=firestore|JWT_SIGNING_KEY=your-secret-key"

Nota: El prefijo ^|^ cambia el delimitador de variables de entorno de , a | porque ALLOWED_DOMAINS contiene comas.

Cómo funciona

• Por defecto, las sesiones de OAuth se almacenan en memoria y se pierden al reiniciar
• Para producción, establece TOKEN_STORE=firestore y JWT_SIGNING_KEY para autenticación persistente entre implementaciones y arranques en frío
• En plataformas sin servidor (Cloud Run, etc.), establece MCP_STATELESS=true — las sesiones de MCP se mantienen en memoria, por lo que el escalado a cero las elimina. El modo sin estado desactiva por completo el seguimiento de sesiones; cada solicitud se autentica de forma independiente mediante el flujo de tokens JWT/Firestore
• ALLOWED_DOMAINS restringe el acceso a dominios específicos de Google Workspace
• Los tokens de acceso se actualizan automáticamente; las sesiones inactivas caducan después de 30 días
• Los usuarios pueden revocar el acceso en cualquier momento mediante Permisos de la cuenta de Google

Actualización de tu implementación

Combinar cambios en main no actualiza automáticamente tu servicio de Cloud Run. Cada implementación es independiente — debes volver a implementar manualmente cuando quieras nuevas funciones o correcciones.

Para actualizar:

1. Obtén el código más reciente:

   git pull origin main
   

2. Vuelve a implementar en Cloud Run:

   gcloud run deploy your-service-name --source . --region your-region
   

   Tus variables de entorno existentes se conservan — no es necesario pasar --set-env-vars nuevamente.

Cuándo volver a implementar:

• Correcciones de errores y parches de seguridad — vuelve a implementar lo antes posible
• Nuevas funciones — vuelve a implementar cuando te convenga
• Cambios importantes — consulta las notas de la versión antes de volver a implementar

Puedes verificar tu versión actual contra la última versión en la página de versiones.

---

Opciones de autenticación

OAuth (predeterminado)

Pasa las credenciales de tu cliente de OAuth de Google Cloud como variables de entorno:

Variable	Descripción
GOOGLE_CLIENT_ID	ID de cliente de OAuth de Google Cloud Console
GOOGLE_CLIENT_SECRET	Secreto del cliente de OAuth de Google Cloud Console

Cuenta de servicio (empresarial)

Para Google Workspace con delegación de todo el dominio:

Variable	Descripción
SERVICE_ACCOUNT_PATH	Ruta al archivo JSON de la clave de la cuenta de servicio
GOOGLE_IMPERSONATE_USER	Correo del usuario a suplantar (opcional)

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/path/to/service-account-key.json",
        "GOOGLE_IMPERSONATE_USER": "user@yourdomain.com"
      }
    }
  }
}

Almacenamiento de tokens

Los tokens de actualización de OAuth se almacenan en ~/.config/google-docs-mcp/token.json (respeta XDG_CONFIG_HOME). Los ID de cliente de OAuth y los secretos de cliente no se almacenan en el archivo de tokens. Para volver a autorizar, ejecuta el comando auth nuevamente o elimina el archivo de tokens.

Múltiples cuentas de Google

Establece GOOGLE_MCP_PROFILE para almacenar tokens en un subdirectorio específico del perfil. Esto permite usar diferentes cuentas de Google para diferentes proyectos:

Variable	Descripción
GOOGLE_MCP_PROFILE	Nombre del perfil para almacenamiento aislado de tokens (opcional)

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "...",
        "GOOGLE_CLIENT_SECRET": "...",
        "GOOGLE_MCP_PROFILE": "work"
      }
    }
  }
}

Los tokens se almacenan por perfil:

~/.config/google-docs-mcp/
├── token.json              # default (no profile)
├── work/token.json         # GOOGLE_MCP_PROFILE=work
├── personal/token.json     # GOOGLE_MCP_PROFILE=personal

Sin GOOGLE_MCP_PROFILE, el comportamiento no cambia.

---

Limitaciones conocidas

• Anclaje de comentarios: Los comentarios creados programáticamente aparecen en la lista de comentarios pero no están anclados visiblemente al texto en la interfaz de Google Docs. Esta es una limitación de la API de Google Drive.
• Anclaje de comentarios en Hojas de cálculo: Los comentarios de hojas de cálculo creados mediante API pueden almacenar metadatos de anclaje, pero los editores de Google Workspace tratan los anclajes de la API de Drive como comentarios sin anclar. Use createSheetsComment con includeCellLink=true para obtener un enlace clicable a la celda de destino, o createSheetsCellNote cuando el texto de revisión deba adjuntarse a la propia celda.
• Resolución de comentarios: El estado de resuelto puede no persistir en la interfaz de Google Docs.
• Documentos convertidos: Los documentos convertidos desde Word pueden no admitir todas las operaciones de la API.
• Imágenes Markdown: Aún no compatibles en la conversión de Markdown a Docs.
• Listas profundamente anidadas: Las listas con 3 o más niveles de anidación pueden tener peculiaridades de formato.
• Eliminación definitiva de Gmail: trashMessage mueve los mensajes a la Papelera (reversible). La eliminación permanente requiere el alcance más amplio https://mail.google.com/ y no está expuesta en v0.1.
• Archivos adjuntos de Gmail: getMessage devuelve metadatos de archivos adjuntos pero aún no descarga los bytes de los archivos adjuntos.
• Envío de correos HTML de Gmail: sendEmail envía solo texto plano. Para cuerpos HTML, pegue el HTML en el campo body — se entregará como texto, no se renderizará.
• Alcance de Calendar: calendar.events permite operaciones CRUD de eventos en calendarios existentes pero no puede crear ni eliminar calendarios completos.
• La API de Apps Script está desactivada por defecto: cada cuenta debe habilitarla una vez en https://script.google.com/home/usersettings. Las herramientas no pueden activarla por usted.
• Implementaciones de Apps Script: las herramientas editan el código fuente del proyecto. La creación de versiones, implementaciones y disparadores instalables aún no está expuesta — los disparadores simples como onEdit y onOpen funcionan sin nada de eso.
• Eventos recurrentes de Calendar: updateEvent y deleteEvent modifican toda la serie recurrente a menos que apunte a un ID de instancia específico devuelto por listEvents con singleEvents=true.

Solución de problemas

• El servidor no se inicia:
  • Verifique que GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET estén configurados en el bloque env de su configuración de MCP.
  • Intente ejecutar manualmente: npx @a-bonus/google-docs-mcp y revise stderr para ver errores.
• Errores de autorización:
  • Asegúrese de que las API de Docs, Sheets, Drive, Gmail y Calendar estén habilitadas en Google Cloud Console.
  • Confirme que su correo electrónico esté listado como Usuario de prueba en la pantalla de consentimiento de OAuth y que todos los alcances requeridos (Docs, Sheets, Drive, gmail.modify, calendar.events) estén agregados a la pantalla de consentimiento.
  • Reautorice: npx @a-bonus/google-docs-mcp auth
  • Elimine ~/.config/google-docs-mcp/token.json y reautorice si está actualizando — los alcances de Gmail y Calendar se agregaron en versiones posteriores, por lo que los tokens existentes deben actualizarse.
  • Los usuarios remotos (Cloud Run) deben cerrar sesión y volver a iniciarla desde su cliente MCP para que Google reemita el consentimiento con la nueva lista de alcances.
• Errores de pestañas:
  • Use listTabs para ver los IDs de pestañas disponibles.
  • Omita tabId para documentos de una sola pestaña.
• "Page not found" en claude.ai durante el inicio de sesión de OAuth (implementaciones remotas):
  • Síntoma: al hacer clic en Conectar en un conector MCP personalizado se llega a la página "Page not found" de Claude en lugar de la pantalla de inicio de sesión de Google.
  • Causa: inicio en frío de Cloud Run. La primera solicitud a un servicio inactivo agota el tiempo de espera antes de que el contenedor termine de iniciarse, y Claude enruta la redirección fallida a su página 404.
  • Solución alternativa: actualice la página forzosamente (Cmd+Shift+R en macOS, Ctrl+Shift+R en Windows/Linux). La segunda solicitud llega a una instancia ya activa y el flujo de OAuth continúa normalmente.
  • Solución permanente: configure --min-instances=1 en su servicio de Cloud Run para mantener una instancia siempre activa (gcloud run services update <service> --region <region> --min-instances=1). Cuesta aproximadamente $2–3/mes por la reserva de memoria.
• Reautenticación inesperada después de una reimplementación (implementaciones remotas):
  • Causa: JWT_SIGNING_KEY se genera automáticamente en cada inicio del contenedor, por lo que las reimplementaciones invalidan todas las sesiones emitidas anteriormente.
  • Solución: configure una variable de entorno JWT_SIGNING_KEY estable en el servicio de Cloud Run para que sobreviva a los reinicios: gcloud run services update <service> --region <region> --update-env-vars JWT_SIGNING_KEY=$(openssl rand -hex 32). Las sesiones emitidas después de este cambio sobrevivirán a futuras reimplementaciones.
• Alto uso de CPU con múltiples sesiones MCP: Algunos clientes llaman a tools/list con mucha frecuencia. De lo contrario, FastMCP recalcula el JSON Schema para cada herramienta en cada solicitud, lo que puede saturar un núcleo de CPU por proceso. Este servidor precalcula la carga útil una vez antes de que stdio se inicie y reemplaza el manejador tools/list con una instantánea en caché. Si aún ve una carga sostenida, capture unos segundos con sample <pid> 1 10 (macOS) o node --cpu-prof e infórmelo.

---

Detalles de configuración de Google Cloud

Instrucciones paso a paso de Google Cloud Console

Para implementación remota, cree un cliente OAuth de tipo Aplicación web (no Aplicación de escritorio). Use Aplicación de escritorio solo para uso local de stdio.

1. Vaya a Google Cloud Console: Abra console.cloud.google.com
2. Crear o seleccionar un proyecto: Haga clic en el menú desplegable del proyecto > "NEW PROJECT". Asígnele un nombre (p. ej., "MCP Docs Server") y haga clic en "CREATE".
3. Habilitar APIs:
   • Navegue a "APIs & Services" > "Library"
   • Busque y habilite: Google Docs API, Google Sheets API, Google Drive API, Gmail API, Google Calendar API
4. Configurar la pantalla de consentimiento de OAuth:
   • Vaya a "APIs & Services" > "OAuth consent screen"
   • Elija "External" y haga clic en "CREATE"
   • Complete: App name, User support email, Developer contact email
   • Haga clic en "SAVE AND CONTINUE"
   • Agregue alcances: documents, spreadsheets, drive, gmail.modify, calendar.events
   • Haga clic en "SAVE AND CONTINUE"
   • Agregue su correo de Google como Usuario de prueba
   • Haga clic en "SAVE AND CONTINUE"
5. Crear credenciales:
   • Vaya a "APIs & Services" > "Credentials"
   • Haga clic en "+ CREATE CREDENTIALS" > "OAuth client ID"
   • Tipo de aplicación: "Desktop app"
   • Haga clic en "CREATE"
   • Copie el Client ID y el Client Secret

---

Contribuciones

¡Las contribuciones son bienvenidas! Consulte CONTRIBUTING.md para la configuración de desarrollo, la descripción general de la arquitectura y las pautas.

Licencia

MIT -- consulte LICENSE para más detalles.