gdrive-write-mcp

Un servidor MCP que da a los asistentes de IA acceso de escritura real a Google Drive — actualizaciones de contenido in situ, adiciones y ediciones de buscar/reemplazar que conservan el ID del archivo, la configuración de uso compartido, los comentarios y el historial de revisiones.

El problema

La mayoría de las integraciones de Google Drive para asistentes de IA son de solo lectura y creación. Pueden buscar archivos, leerlos, crear nuevos y mover los antiguos a la papelera, pero no tienen forma de cambiar el contenido de un archivo que ya existe.

Eso parece una brecha pequeña. No lo es. Sin escrituras in situ, "editar este documento" se convierte en:

1. Leer el archivo.

2. Crear un nuevo archivo con el contenido corregido.

3. Enviar el antiguo a la papelera.

El resultado técnicamente tiene el texto correcto, pero todo lo demás está mal:

gdrive-write-mcp llena ese vacío. La API de Drive de Google siempre ha admitido actualizaciones de contenido in situ; este es un servidor pequeño y enfocado que las expone a través de MCP.

Related MCP server: Google Docs MCP Server

Lo que hace

Edición

• replace_in_file — buscar y reemplazar por coincidencia exacta. La herramienta a la que recurrir por defecto: no requiere reenviar el documento completo y no puede eliminar accidentalmente contenido que nunca se mencionó.

• append_to_file / prepend_to_file — añadir a cualquiera de los extremos, sin reenviar lo que ya está. Hecho para registros, diarios y registros de cambios.

• update_file_content — reemplazar todo el documento. Destructivo por naturaleza, por lo que se documenta al modelo como último recurso, no como opción predeterminada.

Lectura

• read_file — contenido más el revisionToken usado para hacer segura la próxima escritura.

• get_file_metadata — comprobar si un archivo se movió sin descargarlo.

• search_files — sintaxis de consulta de Drive, para que un nombre de archivo pueda convertirse en el ID que las herramientas de escritura necesitan.

• list_revisions — el historial que la edición in situ conserva.

Creación

• create_file — para documentos genuinamente nuevos, con conversión opcional a un Documento o una Hoja de cálculo nativos de Google.

Dos cosas que hace bien

1. Las ediciones concurrentes se rechazan, no se tragan silenciosamente

El modo de fallo de una herramienta de escritura ingenua es silencioso y costoso: lees un documento, piensas durante treinta segundos y lo escribes de nuevo, sobrescribiendo el párrafo que un colega añadió mientras tanto. Nadie recibe un error. Nadie se da cuenta hasta que el párrafo se echa en falta, días después.

Cada lectura aquí devuelve un revisionToken, y cada escritura acepta uno:

read_file(fileId)                    → revisionToken: "0B1a2…"
update_file_content(fileId, content, expectedRevisionToken: "0B1a2…")

Si el archivo ha cambiado, la escritura se rechaza con un error que le dice al modelo exactamente qué hacer — releer, reaplicar, escribir de nuevo — en lugar de un simple 409. Las herramientas dirigidas (replace_in_file, append_to_file, prepend_to_file) leen y escriben dentro de una sola llamada, por lo que llevan la protección automáticamente y nunca tienes que manejar un token tú mismo.

Drive solo expone headRevisionId para archivos con contenido binario real — los Documentos y Hojas de cálculo nativos de Google no tienen uno, que es exactamente donde es más probable la edición humana concurrente, ya que son los archivos que alguien tiene abiertos en una pestaña del navegador. El token recurre a modifiedTime para esos, así que los archivos nativos también están protegidos.

2. Los archivos nativos de Google se manejan con honestidad

Drive almacena dos tipos de cosas muy diferentes, y confundirlos es la fuente más común de errores en las integraciones de Drive:

• Archivos subidos (text/markdown, application/pdf, …) — bytes de entrada, bytes de salida.

• Archivos de editor nativos (application/vnd.google-apps.document, …) — sin bytes propios. Se leen exportándolos a un formato concreto; se escriben subiendo un formato que Drive convierte al ingerirlos.

Este servidor detecta cuál es cuál y enruta en consecuencia. Los Documentos se exportan a markdown en lugar de texto sin formato, específicamente para que un ciclo de lectura-modificación-escritura conserve encabezados, listas y énfasis en lugar de aplanar silenciosamente el documento. Los archivos binarios se codifican en base64 en lugar de decodificarse como UTF-8, de modo que un PDF nunca pueda corromperse al pasar por una herramienta de texto.

Instalación

git clone https://github.com/anaborne/gdrive-write-mcp.git
cd gdrive-write-mcp
npm install
npm run build

Requiere Node 18 o más reciente.

Configuración

Paso 1 — Crear un cliente OAuth de Google

1. Abre la Consola de Google Cloud y crea un proyecto (o elige uno existente).

2. Habilita la API de Google Drive: APIs y servicios → Biblioteca → API de Google Drive → Habilitar.

3. Configura la pantalla de consentimiento de OAuth: APIs y servicios → Pantalla de consentimiento de OAuth. Elige Externa, completa los campos obligatorios y añade tu propia cuenta de Google en Usuarios de prueba. (Mientras la aplicación está en "Pruebas", solo los usuarios de prueba enumerados pueden autorizarla, que es lo que quieres para una herramienta personal).

4. Crea credenciales: APIs y servicios → Credenciales → Crear credenciales → ID de cliente de OAuth → Aplicación de escritorio.

5. Copia el ID de cliente y el Secreto de cliente.

Paso 2 — Obtener un token de actualización

cp .env.example .env
# put GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env
npm run authorize

Esto abre un flujo de consentimiento único en http://localhost:4181 e imprime un token de actualización. Añádelo a .env:

GOOGLE_CLIENT_ID=1234567890-abcdef.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-…
GOOGLE_REFRESH_TOKEN=1//0g…

Paso 3 — Apuntar tu cliente MCP al servidor

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "gdrive-write": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-write-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "…",
        "GOOGLE_CLIENT_SECRET": "…",
        "GOOGLE_REFRESH_TOKEN": "…"
      }
    }
  }
}

Claude Code:

claude mcp add gdrive-write \
  --env GOOGLE_CLIENT_ID=… \
  --env GOOGLE_CLIENT_SECRET=… \
  --env GOOGLE_REFRESH_TOKEN=… \
  -- node /absolute/path/to/gdrive-write-mcp/dist/index.js

Cualquier otra cosa — el servidor habla MCP sobre stdio. Inicia node dist/index.js como subproceso con esas tres variables de entorno establecidas.

Paso 4 — Verificar que funciona

npm run verify

Esto ejecuta una verificación de extremo a extremo real contra tu Drive: inicia el servidor de la misma manera que un cliente MCP, lo conduce a través de stdio con el cliente MCP oficial y verifica el comportamiento que este proyecto afirma — incluyendo que una escritura obsoleta se rechaza, que una escritura rechazada deja el archivo intacto, que el ID del archivo no cambia después de cada edición y que un Documento nativo de Google sobrevive a un ciclo de lectura-edición-lectura como un Documento.

Crea dos archivos temporales en tu Drive y los mueve a la papelera cuando termina, incluso si falla a mitad de camino. Espera una línea de resumen en verde:

✓ ALL 41 CHECKS PASSED — the server works against live Drive.

Si algo falla, la salida nombra la comprobación específica y muestra lo que se devolvió. Las comprobaciones de conflicto y de Documento nativo llevan diagnósticos adicionales que explican qué implica un fallo determinado — un # con barra invertida, por ejemplo, significa que el contenido se importó como texto sin formato en lugar de markdown.

Esto no es una formalidad. La suite de pruebas unitarias estaba en verde con 49 pruebas, y CI pasó, mientras un defecto real permanecía en el código: crear un Documento nativo desde markdown producía silenciosamente un Documento que contenía los caracteres literales # Encabezado. Solo la ejecución en vivo lo detectó, porque el simulacro codificaba la misma suposición errónea que la implementación. Ejecuta esto después de cualquier cambio en drive.ts o mime.ts.

Referencia de herramientas

read_file

Devuelve el contenido más revisionToken, mimeType y modifiedTime. Los archivos nativos se exportan (Documentos → markdown, Hojas de cálculo → CSV, Presentaciones → texto sin formato); los archivos binarios se devuelven codificados en base64.

replace_in_file

La coincidencia es literal, no regex — un . o $1 en tu texto de búsqueda significa exactamente esos caracteres. Si oldString aparece más de una vez y replaceAll es false, la llamada falla en lugar de adivinar, porque una edición silenciosa en la aparición incorrecta es el tipo de error que nadie detecta.

append_to_file / prepend_to_file

Las adiciones repetidas se mantienen uniformemente separadas — sin líneas continuas, sin espacios de líneas en blanco cada vez más amplios.

update_file_content

Reemplaza todo. Sin expectedRevisionToken sobrescribirá los cambios hechos desde tu última lectura del archivo.

create_file

search_files

name contains 'budget'
fullText contains 'quarterly review'
'FOLDER_ID' in parents
mimeType = 'application/vnd.google-apps.document'

get_file_metadata / list_revisions

Ambos toman fileId; list_revisions también toma un pageSize opcional.

Seguridad

Por qué el alcance completo de Drive. Este servidor solicita https://www.googleapis.com/auth/drive por defecto. El alcance más restringido drive.file solo concede acceso a los archivos que la propia aplicación haya creado, algo que no sirve para una herramienta cuyo propósito es editar documentos que ya tienes. Es una contrapartida real, expresada claramente en lugar de oculta: el token puede leer y escribir todo en el Drive de la cuenta autorizada.

Si tu flujo de trabajo solo toca archivos que el asistente crea por sí mismo, solicita el alcance más restringido en su lugar — tanto para el paso de autorización como para el servidor:

GOOGLE_OAUTH_SCOPE=drive.file

Ambos deben coincidir. Un token de actualización lleva consigo el alcance con el que fue concedido, así que emitir un token con uno y ejecutar el servidor con el otro produce confusos errores 403 en el momento de la llamada. El servidor imprime una advertencia en stderr al iniciarse cuando el alcance por archivo está activo, para que un 404 posterior sobre el documento de otra persona no sea un misterio.

Formas de mantener eso acotado:

• Autoriza una cuenta de Google dedicada y comparte solo los archivos o carpetas específicos que quieras que sean accesibles.

• Mantén la aplicación OAuth en modo Pruebas para que solo los usuarios de prueba enumerados puedan autorizarla.

• Revoca el acceso en cualquier momento en myaccount.google.com/permissions.

Manejo del token de actualización. Es una contraseña para tu Drive. Nunca caduca por sí solo. Guárdalo en .env (ignorado por git aquí) o en la configuración de tu cliente MCP, nunca en un archivo versionado. Si se filtra, revócalo en el enlace de arriba: eso lo invalida de inmediato.

Sin telemetría. Este servidor realiza llamadas de red a las APIs de Google y a ninguna otra parte.

Solución de problemas

Error 403: access_denied

Google está rechazando la pantalla de consentimiento antes de que se ejecute cualquiera de este código. auth/drive es un alcance restringido — el nivel más estricto de Google — y los alcances restringidos se bloquean a menos que la aplicación esté configurada para permitirlos. En Google Auth Platform, comprueba en este orden:

1. Audiencia → el estado de publicación es "Pruebas", no "En producción". Una aplicación no verificada en producción no puede usar alcances restringidos en absoluto, para nadie, ni siquiera para su propio autor. El modo Pruebas los permite para hasta 100 usuarios de prueba enumerados sin verificación.

2. Audiencia → Usuarios de prueba incluye la cuenta exacta con la que inicias sesión.

3. Marca → el nombre de la aplicación, el correo electrónico de soporte al usuario y el correo electrónico de contacto del desarrollador están todos guardados. Una pantalla de consentimiento incompleta no es válida.

Los cambios tardan unos minutos en propagarse. Si aún falla inmediatamente después de una edición, espera cinco minutos y vuelve a intentarlo.

Para evitarlo por completo, solicita el alcance por archivo no restringido, que nunca se bloquea:

GOOGLE_OAUTH_SCOPE=drive.file npm run authorize

Cada archivo que toca npm run verify es uno que crea él mismo, por lo que la suite de verificación completa pasa con drive.file — algo útil para confirmar que el servidor funciona mientras la configuración del consentimiento se sigue resolviendo. No accederá a documentos creados en otro lugar, por lo que es una vía de diagnóstico, no una permanente.

Desarrollo

npm install
npm run build       # compile TypeScript to dist/
npm test            # build, then run the unit suite (no network, no credentials)
npm run verify      # end-to-end check against a real Drive account
npm run typecheck   # type-check without emitting
npm run watch       # rebuild on change

npm test y npm run verify responden a preguntas distintas. La suite unitaria simula la API de Drive: demuestra que la lógica es correcta, se ejecuta en CI y no necesita credenciales. npm run verify demuestra que la integración es correcta — que Google se comporta realmente como este servidor supone, en particular en la conversión de archivos nativos y los tokens de revisión. Un cambio en drive.ts o mime.ts debe comprobarse con ambos.

El código está organizado de modo que las partes que pueden corromper silenciosamente un documento se pueden probar sin tocar la red:

src/
  index.ts    entry point; stdio transport
  auth.ts     OAuth client from environment
  drive.ts    Drive operations, incl. the concurrency guard
  edits.ts    pure text transforms — no I/O, fully unit-tested
  mime.ts     native vs. binary vs. textual classification
  tools.ts    MCP tool definitions and handlers
  errors.ts   error types written to be actionable by a model

La suite cubre los casos límite de buscar/reemplazar (literales que parecen expresiones regulares, $& en los reemplazos, objetivos multilínea, coincidencias ambiguas), la lógica de los puntos de inserción para añadir al principio y al final, la clasificación MIME y la protección de concurrencia — incluido que una escritura en conflicto nunca llega a la API.

Contribuciones

Las incidencias y las pull requests son bienvenidas. Para un cambio de cualquier tamaño, abre primero una incidencia para que el enfoque pueda acordarse antes del trabajo.

Si añades una herramienta, añade pruebas para su lógica pura y escribe su descripción para el modelo que la leerá: di cuándo recurrir a ella en lugar de sus vecinas, no solo qué hace.

Licencia

MIT — consulta LICENSE.