Google Documents MCP

Servidor Model Context Protocol para Google Docs — asistente documental académico.

Beta cerrada: el OAuth de Google está en modo Testing. Solo pueden autenticarse los usuarios añadidos manualmente como test users por el maintainer.

npx @0pvalencia/google-documents-mcp login

Características

• Un solo login en el navegador — sin crear proyectos en Google Cloud.
• Sesión persistente por usuario en el directorio estándar del sistema.
• Herramientas MCP para gestión, edición, formato y flujos académicos.
• Resources de guía (google-documents://guides/…) y prompts reutilizables para informes largos.
• Comando doctor con diagnóstico claro.
• Compatible con Cursor, VS Code, Claude Desktop y OpenCode (stdio).

Herramientas disponibles

Documentos / Archivo (Drive)

| Herramienta | Resultado | | --- | --- | | list_documents / create_document / read_document / get_document | listar, crear, texto, JSON | | get_document_metadata / get_document_owners / get_document_folder | metadatos Drive | | rename_document / move_document / duplicate_document | renombrar, mover, copiar | | star_document / create_shortcut | destacado y acceso directo | | trash_document / restore_from_trash / list_trashed_documents / delete_document_permanently | papelera | | export_document | docx/pdf/odt/txt/html/epub/rtf/markdown (base64) | | list/get/create/update/delete_permission | compartir | | list/get_revision / keep_revision_forever / create_document_revision | historial | | get_page_setup / update_document_style | página | | list/create/delete_drive_comment | comentarios Drive |

Edición

| Herramienta | Parámetros | | --- | --- | | append_text / append_section | texto al final / sección con heading | | insert_text | documentId, text, index | | replace_text | documentId, findText, replaceText, matchCase? | | delete_text | documentId, startIndex, endIndex | | move_content | documentId, startIndex, endIndex, destinationIndex |

Formato

| Herramienta | Parámetros | | --- | --- | | get_headings_compact | solo encabezados (preferido para jerarquía/TOC) | | get_document_structure | bloques completos (tablas, índices de inserción) | | apply_format | negrita, cursiva, tachado, linkUrl, fuente, alineación, sangría | | apply_heading / apply_heading_levels / apply_heading_by_title | TITLE / HEADING_1–3 (uno, lote o por texto) | | create_table | rows, columns, index, data (celdas) | | insert_table_row / insert_table_column | filas/columnas | | delete_table_row / delete_table_column | eliminar fila/col | | merge_table_cells / update_table_cell_style | fusionar / fondo-bordes | | search_images | Wikimedia Commons → insertUrl (no inventar URLs) | | insert_image | insertUrl; si falla, rehostViaDrive | | list_images / replace_image | inlineObjects / replaceImage API | | insert_diagram | Mermaid → Drive → imagen | | create_paragraph_bullets / delete_paragraph_bullets | listas Docs | | insert_page_break / insert_section_break | saltos | | create_header / create_footer / delete_* | encabezado/pie | | create_footnote | nota al pie | | update_document_style | márgenes, pageSize, fondo | | list/create/delete/replace_named_range* | rangos nombrados |

Académicas

| Herramienta | Uso | | --- | --- | | create_academic_structure | Portada real + secciones con encabezados | | format_academic_document | APA 7: márgenes 1", TNR 12, doble espacio; preserva TITLE/H1–H3 | | repair_academic_document | Repara capítulos (incl. reorden numérico), tablas Markdown, scaffold vacío, encabezados vacíos e índice | | insert_table_of_contents | Regenera Índice con enlaces #heading= | | insert_citation / append_bibliography | Citas y referencias | | generate_academic_document | Portada + estructura + APA + índice | | create_document_revision | Checkpoint keepForever en Drive |

Resources (guías para agentes)

| URI | Contenido | | --- | --- | | google-documents://guides/long-report-playbook | Cómo hacer informes largos (relleno sección a sección) | | google-documents://guides/tool-orchestration | Orden correcto de tools | | google-documents://guides/anti-patterns | Errores típicos que rompen Docs | | google-documents://guides/tools-overview | Mapa de categorías |

Prompts MCP

| Prompt | Uso | | --- | --- | | long_academic_report | Informe largo desde cero (scaffold + presupuesto de palabras) | | fill_report_to_length | Llenar un Doc ya scafoldeado hasta N páginas | | expand_section | Ampliar un capítulo concreto | | repair_broken_report | Reparar TOC/headings/tablas rotas | | safe_edit | Edición puntual con índices seguros |

Nota: pages en generate_academic_document no rellena el cuerpo; solo crea el andamiaje. Los prompts enseñan a escribir capítulo a capítulo.

Instalación y primer uso

1. Autentica:

npx @0pvalencia/google-documents-mcp login

Si ya tenías sesión con el scope anterior (drive.metadata.readonly), vuelve a ejecutar login para conceder drive (necesario para duplicar/eliminar).

2. Autoriza Google en el navegador (debes estar en la lista de test users).

3. Conecta el MCP en tu cliente:

   • Cursor
   • VS Code
   • Claude Desktop
   • Claude Code
   • OpenCode
   • Índice de clientes

Solo necesitas autenticarte una vez. Comprueba el estado:

npx @0pvalencia/google-documents-mcp doctor

Beta cerrada / test users

Actualmente Google OAuth está en modo testing. Solo usuarios agregados manualmente como test users pueden autenticarse.

Si el login falla:

1. Pide al maintainer que te añada como test user.
2. Vuelve a ejecutar login.

Error 400 / el navegador no abre en Windows

Desde 0.6.3 el login abre el navegador directamente y nunca imprime la URL OAuth en la terminal. En Windows usa rundll32 para no romper los & de la query.

Comandos CLI

google-documents-mcp                 Inicia el servidor MCP (stdio)
google-documents-mcp login           Inicia sesión con Google
google-documents-mcp logout          Cierra la sesión local
google-documents-mcp doctor          Verifica la sesión y el acceso a las APIs
google-documents-mcp version         Muestra la versión
google-documents-mcp help            Lista los comandos

Doctor

Comprueba: sesión, refresh token, usuario autenticado, Docs API, Drive API y permisos.

Dónde se guarda la sesión

| Sistema | Ubicación | | --- | --- | | Linux | ~/.config/google-documents-mcp/ | | macOS | ~/Library/Application Support/google-documents-mcp/ | | Windows | %APPDATA%\google-documents-mcp\ |

npx @0pvalencia/google-documents-mcp logout

Arquitectura

src/
├── auth/                 # OAuth, PKCE, sesión
├── cli/                  # login, logout, doctor, help
├── config/               # storage y rutas del SO
├── server/
│   ├── mcp.ts            # tools + services
│   └── stdio.ts          # transporte local
├── transports/
│   └── stdio.ts
├── services/
│   └── docs/             # Docs API (documents, content, formatting, academic)
├── tools/docs/
│   ├── documents/
│   ├── content/
│   ├── formatting/
│   └── academic/
├── prompts/              # prompts MCP (informes largos, repair, safe edit)
├── resources/            # resources google-documents://guides/*
├── schemas/
├── types/
└── utils/

Las tools solo validan parámetros y delegan en services/.

Desarrollo (maintainers)

npm install
cp .env.example .env
npm run dev login
npm run check
npm test

Contribuir

1. Fork + rama descriptiva.
2. Tipado estricto, sin any.
3. Nuevas herramientas solo vía services/ + tools/.
4. npm run check y npm test antes del PR.

Licencia

MIT