title: "Google Drive MCP Server" date: 2026-08-19 tags:

• proyecto/workspace

• subproyecto/tools

• tipo/guide

• área/tech

• fecha/2026-08-19

Google Drive MCP Server

Servidor local MCP para Cursor, Claude Code y Claude Desktop. A través de él, el agente busca y lee archivos en Google Drive, crea y edita Google Docs y Google Sheets.

Los Google Docs se convierten a Markdown al leerlos, las hojas de cálculo a CSV y las presentaciones a texto. Los Docs se pueden editar de forma puntual: inserción, sustitución, estilos, encabezados, listas, renombrado, duplicado. En Sheets: valores, formatos, pestañas, filas y columnas. Funciona tanto con el Drive personal como con Shared drives.

Repositorio: https://github.com/Stillfrozen/gdrive-mcp
Basado en wagnerlabs/gdrive-mcp.

Las claves OAuth viven solo en tu disco. No llegan a git.

Instalación paso a paso en Google Cloud (proyecto, API, OAuth de escritorio, test users): docs/INSTALL.ru.md

Inicio rápido

Se necesitan Node.js 18+ (mejor 20) y una cuenta de Google desde cuyo Drive vayas a trabajar.

git clone https://github.com/Stillfrozen/gdrive-mcp.git
cd gdrive-mcp
./scripts/install.sh

El script instala las dependencias, compila el proyecto y te guía por Google Cloud: proyecto, API, pantalla de consentimiento, cliente de escritorio, inicio de sesión en el navegador. Al final imprime el fragmento listo para el cliente MCP.

Ver los pasos sin cambios:

./scripts/install.sh --dry-run

Si quieres hacer clic tú mismo en Console, todo el desglose de pantallas está en docs/INSTALL.ru.md.

Cursor

En ~/.cursor/mcp.json (o .cursor/mcp.json en el proyecto), solo la ruta absoluta:

{
  "mcpServers": {
    "gdrive": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-mcp/dist/index.js"],
      "env": {
        "GDRIVE_OAUTH_PATH": "/absolute/path/to/gdrive-mcp/credentials/gcp-oauth.keys.json",
        "GDRIVE_CREDENTIALS_PATH": "/absolute/path/to/gdrive-mcp/credentials/.gdrive-server-credentials.json"
      }
    }
  }
}

El bloque env no es obligatorio si los JSON están en credentials/ del repositorio. Si el archivo ya tiene otros servidores, añade "gdrive" dentro de mcpServers, sin sobrescribir el resto.

Después, Cursor → Settings → MCP → Reload. El indicador gdrive debería ponerse verde.

Claude Code CLI

claude mcp add --scope user gdrive -- node /absolute/path/to/gdrive-mcp/dist/index.js

--scope user instala el servidor globalmente. Para quitarlo: claude mcp remove gdrive.

Claude Desktop

En claude_desktop_config.json:

{
  "mcpServers": {
    "gdrive": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-mcp/dist/index.js"]
    }
  }
}

Related MCP server: Google Drive MCP Server

Herramientas

Lectura

Escritura: Sheets

Escritura: Docs

Cómo se escriben los valores en las celdas

En gdrive_update_sheet y gdrive_append_sheet, el parámetro value_input_option:

• USER_ENTERED (por defecto): como al introducir en la interfaz de Sheets. La fórmula =SUM(A1:A10) se ejecutará; los números y las fechas se formatearán.

• RAW: tal cual. La cadena =SUM(A1:A10) permanecerá como texto.

Cómo se leen los archivos

gdrive_read_file exporta por sí mismo los documentos de Workspace:

Toda la hoja de cálculo (pestañas, estructura, escritura) tómala mediante gdrive_get_spreadsheet_info y las herramientas de escritura de Sheets, no mediante gdrive_read_file.

Para párrafos, encabezados, listas y ediciones por anclas en un Doc, usa gdrive_get_document_info. La respuesta incluye text en bruto y displayText sin el salto de línea final del párrafo; displayText suele ser más seguro como ancla. Markdown se obtiene más rápido con gdrive_read_file.

Modelo de seguridad

Varias capas: anotaciones MCP, «primero lee», para Docs además revisión y anclas, para Sheets, verificación de los valores actuales.

1. Anotaciones de las herramientas

Cada herramienta declara MCP annotations. El cliente puede pedir confirmación antes de una operación destructiva. Consulta las columnas Destructivo / Idempotente en las tablas anteriores.

2. Primero leer, luego escribir

El servidor recuerda qué hojas de cálculo y Docs ha abierto ya el agente en esta sesión.

La hoja de cálculo se considera leída después de:

• gdrive_read_file (celdas como CSV)

• gdrive_get_spreadsheet_info (estructura y pestañas)

• gdrive_create_sheet (el agente acaba de crear el archivo)

El Doc se considera leído después de:

• gdrive_read_file (Markdown + revisión, si Google la ha proporcionado)

• gdrive_get_document_info (pestañas o texto estructurado)

• gdrive_create_doc

Cualquier escritura sin este paso se rechaza:

You must read this spreadsheet before writing to it…

You must read this document before writing to it…

De este modo el agente apunta con menos frecuencia al archivo equivocado. La lista se reinicia al reiniciar el proceso (cada sesión MCP comienza de nuevo).

gdrive_get_file no entra aquí: son solo metadatos de Drive, no contenido.

3. Escritura en Docs teniendo en cuenta la revisión

La edición está vinculada a la revisión que el agente leyó por última vez:

• conflict_mode: "strict" (por defecto): Docs requiredRevisionId. Si el documento ha sido modificado, la escritura falla.

• conflict_mode: "merge": Docs targetRevisionId. Google fusionará con los cambios de otros si es posible.

La caché del contenido estructurado vive en la sesión después de gdrive_get_document_info include_content=true. Las herramientas de ancla (gdrive_insert_doc_text, gdrive_replace_doc_text, gdrive_update_doc_paragraph_style, gdrive_update_doc_list) la usan mientras la revisión sea la misma. De lo contrario, el servidor vuelve a tomar una instantánea.

Para una sustitución puntual de texto se puede pasar expected_text: antes de enviar, el servidor comprobará que en el rango está exactamente esa cadena.

En las herramientas de ancla gdrive_delete_doc_text y gdrive_replace_doc_text, el servidor recorta por sí solo solo el salto de línea final del párrafo si la coincidencia llega al final de la pestaña. La API de Docs no elimina un rango con el newline terminal de un segmento. Los start_index / end_index explícitos no hacen esto: el newline final debe excluirse manualmente.

4. Precondición para Sheets

gdrive_update_sheet tiene un expected_current_values opcional: una matriz bidimensional con la misma forma que values. El servidor lee las celdas y las compara. Si no coinciden, la escritura se rechaza y en el error se incluye el contenido real.

• Edición puntual (una celda, una fórmula): pasa expected_current_values.

• Operación masiva (miles de filas): no lo pases; de lo contrario duplicarás las peticiones y chocarás con la cuota.

include_previous_values: true devolverá los valores anteriores para auditoría. Si se especifica expected_current_values, los valores anteriores siempre llegan.

Reversión

Las ediciones de Docs y Sheets son visibles en el historial de versiones de Google Workspace. Se puede revertir allí.

Ninguna herramienta elimina un archivo completo de Drive. Las operaciones destructivas son solo dentro del Doc y dentro de la hoja de cálculo. Para eliminar un archivo, solo a través de la interfaz de Drive.

Configuración

Las rutas de las claves se pueden sobrescribir con variables de entorno:

Actualización

Después de git pull, ejecuta el upgrade. Recompilará el proyecto y, si en setup-manifest.json han aparecido API o scopes, pedirá volver a hacer el auth:

cd /path/to/gdrive-mcp
git pull
./scripts/upgrade.sh

Si el manifiesto no ha cambiado, el script solo recompilará y te dirá que estás al día. Cursor tomará dist/ después de Reload MCP. No es necesario volver a registrar el servidor.

Sobre el scope: el servidor solicita drive completo, no el limitado drive.file. Esto es más amplio que la recomendación mínima de Google, pero de otro modo no se puede leer un archivo accesible arbitrario ni escribir en Docs ya existentes (rename, duplicate, ediciones). El scope documents es necesario para la lectura estructurada y batchUpdate.

En una aplicación External en estado Testing, el refresh token vive 7 días. Después, invalid_grant y de nuevo npm run auth. Más detalles y opciones (Internal / Publish) en docs/INSTALL.ru.md.

Limitaciones

• gdrive_create_sheet coloca la hoja de cálculo en la raíz de Drive. No se puede elegir carpeta.

• gdrive_read_file para Sheets devuelve CSV solo de la primera pestaña. Las demás pestañas, mediante gdrive_get_spreadsheet_info.

• gdrive_read_file para Docs siempre devuelve Markdown. Pestañas, límites de párrafos, listas, anclas: gdrive_get_document_info.

• Antes de cambiar el formato y la estructura de un Doc, lee primero gdrive_get_document_info include_content=true.

• gdrive_replace_all_doc_text por defecto toca la primera pestaña. Para todas las pestañas, solo con all_tabs: true explícito.

Desarrollo

npm install
npm run dev          # tsx, без сборки
npm run build
npm test
npm run test:live    # живой Google Doc, нужны сохранённые credentials
npm run test:watch

npm run test:live crea un documento temporal, inserta el texto mediante el mismo flujo que MCP, lo verifica a través de gdrive_get_document_info y al final coloca el archivo en la papelera.

Licencia

MIT