gdocs — bucle de revisión de Google Docs para Claude Code

Un servidor MCP que permite a Claude Code leer un documento de Google Docs y sus hilos de comentarios, y luego escribir correcciones de vuelta en el mismo documento en la misma URL.

Creado para el bucle en el que el Markdown de un repositorio es la fuente de verdad y Google Docs es solo el lugar de revisión. Elimina el ir y venir de copiar y pegar: ni pegar el borrador en Docs ni pegar los comentarios de los revisores de vuelta en la terminal.

Se instala a nivel de usuario, así que funciona en todos los proyectos.

Requisitos

• Node 18+

• La CLI de claude

• Una cuenta de Google y unos 10 minutos en Google Cloud Console

Instalación

git clone https://github.com/uma-victor1/gdocs-mcp.git
cd gdocs-mcp
./install.sh

Eso instala las dependencias, verifica que el servidor arranca y lo registra con Claude Code a nivel de usuario. Luego haz tú mismo los dos pasos de credenciales que aparecen a continuación.

1. Google Cloud, una sola vez

1. Crea un proyecto: https://console.cloud.google.com/projectcreate

2. Habilita Google Docs API y Google Drive API (APIs y servicios > Biblioteca)

3. Pantalla de consentimiento OAuth: el tipo de usuario Externo es válido para una cuenta personal. En Audiencia, añade tu propia dirección como usuario de prueba — saltarse este paso es la causa más común de que fallen los permisos.

4. Credenciales > Crear credenciales > ID de cliente OAuth > Aplicación de escritorio > Descargar JSON

5. Guárdalo como ~/.config/gdocs-mcp/credentials.json

Las credenciales viven fuera de cualquier repositorio a propósito, así git add -A nunca podrá hacerles commit.

2. Autoriza, una sola vez

npm run auth

Google avisa de que la aplicación no está verificada. Es lo esperado en una aplicación de un solo usuario: Avanzado > Ir a ... (no seguro). El token de actualización se guarda en ~/.config/gdocs-mcp/token.json, con modo 0600.

Reinicia Claude Code y confírmalo con claude mcp list.

La reautorización a los 7 días, y por qué

Mientras la pantalla de consentimiento esté en Pruebas, Google expira el token de actualización cada 7 días. Este es un comportamiento documentado para las aplicaciones externas en pruebas, no es un error, y no hay forma de evitarlo para este conjunto de ámbitos: auth/drive es un ámbito restringido, y publicar en producción con un ámbito restringido en el ámbito de un usuario — no merece la pena para una herramienta de una persona.

Así que, aproximadamente una vez por semana, una llamada de herramienta fallará con «Authorisation expired». La solución:

npm run auth

Quince segundos. Si tienes una cuenta de Google Workspace, puedes evitarlo por completo: crea el proyecto de Cloud dentro de esa organización y ajusta el tipo de usuario de la pantalla de consentimiento a Interno. Las aplicaciones internas no tienen caducidad de 7 días ni lista de usuarios de prueba.

Herramientas

Todas las herramientas aceptan una URL de documento o un simple ID de documento (fileId).

El compromiso de los anclajes de comentarios

Google ancla cada comentario a un tramo de texto. Si se reescribe ese tramo, el hilo se desancla o se auto-resuelve. Así que:

• Arreglos pequeños → replace_text. Los anclajes sobreviven; los revisores conservan sus claves.

• Reescrituras estructurales → push_markdown. Más rápido, pero esperar cierta pérdida de hilos. Muestra cuántos hilos abiertos había antes, para que el daño sea visible y no silencioso.

• Añadir en lugar de cambiar → append_text. Solo inserta al final, así ningún texto existente se mueve y no se rompe ningún anclaje.

• Respuesta antes de reescribir. reply_comment deja un registro de qué cambió y por qué.

Por qué esto y no un servidor listo para usar

Un servidor MCP con el token OAuth de Docs puede leer y reescribir todos los documentos de la cuenta. No existe un MCP de Docs de primera parte de Google ni de Anthropic; todos los publicados son paquetes de terceros de editores individuales. Esto son about 250 líneas sobre SDK MCP de Anthropic y la librería cliente de Google, lo bastante pequeño como para que un proyecto — apenas nada, la suficiente para leerlo antes de confiar.

Modo de solo lectura

claude mcp remove gdocs -s user
claude mcp add gdocs -s user -e GDOCS_MCP_READONLY=1 -- node "$PWD/server.mjs"

Las lecturas continúan funcionando; todas las herramientas de escritura se rechazan. Útil cuando alguien más es propietario del documento.

Solución de problemas

Puedes verificar el servidor de forma independiente en cualquier momento con npm run smoke.

Para probar una herramienta específica sin pasar por Claude Code:

node call.mjs read_comments '{"doc":"https://docs.google.com/document/d/FILEID/edit"}'

Revocar el acceso

Dirígete a https://myaccount.google.com/permissions y borra el archivo ~/.config/gdocs-mcp/token.json.

Estructura

server.mjs         the nine tools
google.mjs         auth + Drive/Docs clients; credential paths
auth.mjs           one-time interactive OAuth   (npm run auth)
smoke.mjs          starts the server, lists tools  (npm run smoke)
call.mjs           invoke one tool from the shell, for debugging
install.sh         deps, verify, register at user scope
docs/guide.html    the setup walkthrough as a standalone page

Licencia

MIT. Véase LICENSE.