Google Docs & Drive

Interactúa con Google Docs y Google Drive para la creación, edición y gestión de documentos, con soporte para unidades compartidas.

GitHub

Documentación

Servidor MCP Ultimate para Google Docs y Drive

Demo Animation

¡Conecta Claude Desktop (u otros clientes MCP) a tus Google Docs y Google Drive!

🔥 **¡Descubre 15 potentes tareas que puedes realizar con este servidor mejorado!**📁 NUEVO: ¡Capacidades completas de gestión de archivos en Google Drive!

Este servidor integral utiliza el Protocolo de Contexto de Modelo (MCP) y la librería fastmcp para proporcionar herramientas para leer, escribir, formatear, estructurar Documentos de Google y gestionar todo tu Google Drive. Actúa como un puente potente, permitiendo que asistentes de IA como Claude interactúen con tus documentos y archivos de forma programática con capacidades avanzadas.

Características:

Acceso y Edición de Documentos

Leer Documentos: Lee contenido con readGoogleDoc (texto plano, estructura JSON o markdown)
Añadir a Documentos: Agrega texto a documentos con appendToGoogleDoc
Insertar Texto: Coloca texto en posiciones específicas con insertText
Eliminar Contenido: Elimina contenido de un documento con deleteRange

Formato y Estilos

Formato de Texto: Aplica estilos enriquecidos con applyTextStyle (negrita, cursiva, colores, etc.)
Formato de Párrafos: Controla el diseño de párrafos con applyParagraphStyle (alineación, espaciado, etc.)
Buscar y Formatear: Formatea por contenido de texto usando formatMatchingText (soporte heredado)

Estructura de Documentos

Tablas: Crea tablas con insertTable
Saltos de Página: Inserta saltos de página con insertPageBreak
Características Experimentales: Herramientas como fixListFormatting para detección automática de listas

🆕 Gestión de Archivos en Google Drive

Descubrimiento de Documentos: Encuentra y lista documentos con listGoogleDocs, searchGoogleDocs, getRecentGoogleDocs
Información de Documentos: Obtén metadatos detallados con getDocumentInfo
Gestión de Carpetas: Crea carpetas (createFolder), lista contenidos (listFolderContents), obtén información (getFolderInfo)
Operaciones con Archivos: Mueve (moveFile), copia (copyFile), renombra (renameFile), elimina (deleteFile)
Creación de Documentos: Crea nuevos documentos (createDocument) o desde plantillas (createFromTemplate)
🚀 Soporte para Unidades Compartidas: Soporte completo para unidades compartidas de Google Workspace. ¡Todas las operaciones ahora funcionan perfectamente con unidades compartidas!

Integración

Autenticación de Google: Autenticación OAuth 2.0 segura con acceso completo a Drive
Compatible con MCP: Diseñado para usarse con Claude y otros clientes MCP
Integración con VS Code: Guía de configuración para la extensión MCP de VS Code

Requisitos Previos

Antes de comenzar, asegúrate de tener:

Node.js y npm: Una versión reciente de Node.js (que incluye npm) instalada en tu computadora. Puedes descargarla desde nodejs.org. (Se recomienda la versión 18 o superior).
Git: Requerido para clonar este repositorio. (Descargar Git).
Una Cuenta de Google: La cuenta que posee o tiene acceso a los Google Docs con los que deseas interactuar.
Familiaridad con la Línea de Comandos: Comodidad básica usando una terminal o símbolo del sistema (como Terminal en macOS/Linux, o Símbolo del sistema/PowerShell en Windows).
Claude Desktop (Opcional): Si tu objetivo es conectar este servidor a Claude, necesitarás tener instalada la aplicación Claude Desktop.

Instrucciones de Configuración

Sigue estos pasos cuidadosamente para poner en marcha tu propia instancia del servidor.

Paso 1: Proyecto de Google Cloud y Credenciales (¡La Parte Importante!)

Este servidor necesita permiso para comunicarse con las APIs de Google en tu nombre. Crearás "claves" especiales (credenciales) que solo usará tu servidor.

Ve a Google Cloud Console: Abre tu navegador web y ve a Google Cloud Console. Es posible que necesites iniciar sesión con tu cuenta de Google.
Crea o Selecciona un Proyecto:
- Si no tienes un proyecto, haz clic en el menú desplegable de proyectos cerca de la parte superior y selecciona "NUEVO PROYECTO". Ponle un nombre (por ejemplo, "Mi Servidor MCP Docs") y haz clic en "CREAR".
- Si tienes proyectos existentes, puedes seleccionar uno o crear uno nuevo.
Habilita las APIs: Necesitas activar los servicios específicos de Google que usa este servidor.
- En la barra de búsqueda de la parte superior, escribe "APIs y Servicios" y selecciona "Biblioteca".
- Busca "API de Google Docs" y haz clic en ella. Luego haz clic en el botón "HABILITAR".
- Busca "API de Google Drive" y haz clic en ella. Luego haz clic en el botón "HABILITAR" (esto suele ser necesario para encontrar archivos o permisos).
Configura la Pantalla de Consentimiento de OAuth: Esta pantalla informa a los usuarios (normalmente solo a ti) qué permisos solicita tu aplicación.
- En el menú de la izquierda, haz clic en "APIs y Servicios" -> "Pantalla de consentimiento de OAuth".
- Elige el Tipo de Usuario: Selecciona "Externo" y haz clic en "CREAR".
- Completa la Información de la Aplicación:
  * Nombre de la aplicación: Ponle un nombre que los usuarios verán (por ejemplo, "Acceso MCP de Claude Docs").
  * Correo electrónico de soporte al usuario: Selecciona tu dirección de correo electrónico.
  * Información de contacto del desarrollador: Introduce tu dirección de correo electrónico.
- Haz clic en "GUARDAR Y CONTINUAR".
- Ámbitos (Scopes): Haz clic en "AÑADIR O QUITAR ÁMBITOS". Busca y añade los siguientes ámbitos:
  * https://www.googleapis.com/auth/documents (Permite leer/escribir documentos)
  * https://www.googleapis.com/auth/drive.file (Permite el acceso a archivos específicos abiertos/creados por la aplicación)
  * Haz clic en "ACTUALIZAR".
- Haz clic en "GUARDAR Y CONTINUAR".
- Usuarios de Prueba: Haz clic en "AÑADIR USUARIOS". Introduce la misma dirección de correo de Google con la que has iniciado sesión. Haz clic en "AÑADIR". Esto te permite a ti usar la aplicación mientras está en modo de "prueba".
- Haz clic en "GUARDAR Y CONTINUAR". Revisa el resumen y haz clic en "VOLVER AL PANEL".
Crea Credenciales (¡Las Claves!):
- En el menú de la izquierda, haz clic en "APIs y Servicios" -> "Credenciales".
- Haz clic en "+ CREAR CREDENCIALES" en la parte superior y elige "ID de cliente de OAuth".
- Tipo de aplicación: Selecciona "Aplicación de escritorio" en el menú desplegable.
- Nombre: Ponle un nombre (por ejemplo, "Cliente de Escritorio MCP Docs").
- Haz clic en "CREAR".
⬇️ DESCARGA EL ARCHIVO DE CREDENCIALES: Aparecerá una ventana mostrando tu ID de cliente. Haz clic en el botón "DESCARGAR JSON".
- Guarda este archivo. Probablemente se llamará algo como client_secret_....json.
- IMPORTANTE: Renombra el archivo descargado exactamente como credentials.json.
⚠️ ADVERTENCIA DE SEGURIDAD: ¡Trata este archivo credentials.json como una contraseña! No lo compartas públicamente y nunca lo subas a GitHub. Cualquier persona con este archivo podría hacerse pasar por tu aplicación (aunque aún necesitaría el consentimiento del usuario para acceder a los datos).

Paso 2: Obtén el Código del Servidor

Clona el Repositorio: Abre tu terminal/símbolo del sistema y ejecuta:
git clone https://github.com/jasonWong-serviceDirect/google-docs-mcp-shared.git mcp-googledocs-server
Navega al Directorio:
cd mcp-googledocs-server
Coloca las Credenciales: Mueve o copia el archivo credentials.json que descargaste y renombraste (del Paso 1.6) directamente dentro de esta carpeta mcp-googledocs-server.

Paso 3: Instala las Dependencias

Tu servidor necesita algunas librerías auxiliares especificadas en el archivo package.json.

En tu terminal (asegúrate de estar dentro del directorio mcp-googledocs-server), ejecuta:
npm install
Esto descargará e instalará todos los paquetes necesarios en una carpeta node_modules.

Paso 4: Compila el Código del Servidor

El servidor está escrito en TypeScript (.ts), pero necesitamos compilarlo a JavaScript (.js) que Node.js pueda ejecutar directamente.

En tu terminal, ejecuta:
npm run build
Esto utiliza el compilador de TypeScript (tsc) para crear una carpeta dist que contiene los archivos JavaScript compilados.

Paso 5: Primera Ejecución y Autorización de Google (Solo una Vez)

Ahora necesitas ejecutar el servidor manualmente una vez para concederle permiso de acceso a los datos de tu cuenta de Google. Esto creará un archivo token.json que guarda tu concesión de permisos.

En tu terminal, ejecuta el servidor compilado usando node:
node ./dist/server.js
Observa la Terminal: El script imprimirá:
- Mensajes de estado (como "Intentando autorizar...").
- Un mensaje "Autoriza esta aplicación visitando esta URL:" seguido de una URL larga de https://accounts.google.com/....
Autoriza en el Navegador:
- Copia la URL larga completa desde la terminal.
- Pega la URL en tu navegador web y presiona Enter.
- Inicia sesión con la misma cuenta de Google que añadiste como Usuario de Prueba en el Paso 1.4.
- Google mostrará una pantalla solicitando permiso para tu aplicación ("Acceso MCP de Claude Docs" o similar) para acceder a Google Docs/Drive. Revisa y haz clic en "Permitir" o "Conceder".
Obtén el Código de Autorización:
- Después de hacer clic en Permitir, tu navegador probablemente intentará redirigir a http://localhost y mostrará un error de "Este sitio no puede ser alcanzado". ¡ESTO ES NORMAL!
- Observa cuidadosamente la URL en la barra de direcciones de tu navegador. Se verá como http://localhost/?code=4/0Axxxxxxxxxxxxxx&scope=...
- Copia la cadena larga de caracteres entre code= y la parte de &scope. Este es tu código de autorización de un solo uso.
Pega el Código en la Terminal: Vuelve a tu terminal donde el script está esperando ("Introduce el código de esa página aquí:"). Pega el código que acabas de copiar.
Presiona Enter.
¡Éxito! El script debería imprimir:
- "¡Autenticación exitosa!"
- "Token almacenado en .../token.json"
- Luego terminará de iniciarse y probablemente imprimirá "Esperando conexión del cliente MCP vía stdio..." o similar, y luego saldrá (o puedes presionar Ctrl+C para detenerlo).
✅ Verifica: Ahora deberías ver un nuevo archivo llamado token.json en tu carpeta mcp-googledocs-server.
⚠️ ADVERTENCIA DE SEGURIDAD: Este archivo token.json contiene la clave que permite al servidor acceder a tu cuenta de Google sin volver a preguntar. Protégelo como una contraseña. No lo subas a GitHub. El archivo .gitignore incluido debería evitar esto automáticamente.

Paso 6: Configura Claude Desktop (Opcional)

Si deseas usar este servidor con Claude Desktop, necesitas indicarle a Claude cómo ejecutarlo.

Encuentra tu Ruta Absoluta: Necesitas la ruta completa al código del servidor.
- En tu terminal, asegúrate de seguir dentro del directorio mcp-googledocs-server.
- Ejecuta el comando pwd (en macOS/Linux) o cd (en Windows, solo muestra la ruta).
- Copia la ruta completa (por ejemplo, /Users/yourname/projects/mcp-googledocs-server o C:\Users\yourname\projects\mcp-googledocs-server).
Localiza mcp_config.json: Encuentra el archivo de configuración de Claude:
- macOS: ~/Library/Application Support/Claude/mcp_config.json (Es posible que necesites usar el menú "Ir" -> "Ir a la carpeta..." del Finder y pegar ~/Library/Application Support/Claude/)
- Windows: %APPDATA%\Claude\mcp_config.json (Pega %APPDATA%\Claude en la barra de direcciones del Explorador de Archivos)
- Linux: ~/.config/Claude/mcp_config.json
- Si la carpeta Claude o el archivo mcpconfig.json no existen, créalos.
Edita mcp_config.json: Abre el archivo en un editor de texto. Añade o modifica la sección mcpServers de la siguiente manera, reemplazando /PATH/TO/YOUR/CLONED/REPO con la ruta absoluta real que copiaste en el Paso 6.1:
{
"mcpServers": {
"google-docs-mcp": {
"command": "node",
"args": [
"/PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js"
],
"env": {}
}
// Añade comas aquí si tienes otros servidores definidos
}
// Otras configuraciones de Claude podrían estar aquí
}
- ¡Asegúrate de que la ruta en "args" sea correcta y absoluta!
- Si el archivo ya existía, fusiona cuidadosamente esta entrada en el objeto mcpServers existente. Asegúrate de que el JSON sea válido (¡revisa las comas!).
Guarda mcp_config.json.
Reinicia Claude Desktop: Cierra Claude por completo y vuelve a abrirlo.

Uso con Claude Desktop

Una vez configurado, deberías poder usar las herramientas en tus conversaciones con Claude:

"Usa el servidor google-docs-mcp para leer el documento con ID YOUR_GOOGLE_DOC_ID."
"¿Puedes obtener el contenido del Google Doc YOUR_GOOGLE_DOC_ID?"
"Añade 'Esto fue añadido por Claude!' al documento YOUR_GOOGLE_DOC_ID usando la herramienta google-docs-mcp."

Ejemplos de Uso Avanzado:

Estilo de Texto: "Usa applyTextStyle para poner el texto 'Important Section' en negrita y rojo (#FF0000) en el documento YOUR_GOOGLE_DOC_ID."
Estilo de Párrafo: "Usa applyParagraphStyle para centrar el párrafo que contiene 'Title Here' en el documento YOUR_GOOGLE_DOC_ID."
Creación de Tablas: "Inserta una tabla de 3x4 en el índice 500 del documento YOUR_GOOGLE_DOC_ID usando la herramienta insertTable."
Formato Heredado: "Usa formatMatchingText para encontrar la segunda instancia de 'Project Alpha' y ponerla en azul (#0000FF) en el documento YOUR_GOOGLE_DOC_ID."

🚀 Compatibilidad con Unidades Compartidas:

¡El servidor ahora es totalmente compatible con las unidades compartidas de Google Workspace! Puedes:

Listar el contenido de unidades compartidas: "Lista todos los documentos en la unidad compartida SHARED_DRIVE_ID usando listGoogleDocs con corpora='drive'"
Buscar en todas las unidades: "Busca 'budget' en todas mis unidades usando searchGoogleDocs con corpora='allDrives'"
Crear en unidades compartidas: "Crea un nuevo documento en la unidad compartida SHARED_DRIVE_ID usando createDocument con el parámetro driveId"
Listar carpetas en unidades compartidas: "Lista el contenido de la carpeta FOLDER_ID en la unidad compartida DRIVE_ID usando listFolderContents"

El parámetro corpora controla el ámbito de búsqueda:

'user' (predeterminado): Solo la unidad personal del usuario
'drive': Una unidad compartida específica (requiere driveId)
'allDrives': Todas las unidades accesibles, incluidas las unidades compartidas

Recuerda reemplazar YOUR_GOOGLE_DOC_ID con el ID real de la URL de un documento de Google (la cadena larga entre /d/ y /edit).

Claude iniciará automáticamente tu servidor en segundo plano cuando sea necesario usando el comando que proporcionaste. Ya no necesitas ejecutar node ./dist/server.js manualmente.

Seguridad y Almacenamiento de Tokens

.gitignore: Este repositorio incluye un archivo .gitignore que debería evitar que confirmes accidentalmente tus archivos sensibles credentials.json y token.json. No elimines estas líneas de .gitignore.
Almacenamiento de Tokens: Este servidor almacena el token de autorización de Google (token.json) directamente en la carpeta del proyecto por simplicidad durante la configuración. En entornos de producción o más sensibles a la seguridad, considera almacenar este token de forma más segura, como usando llaveros del sistema, archivos cifrados o servicios dedicados de gestión de secretos.

Solución de Problemas

Claude muestra "Failed" o "Could not attach":
- Verifica dos veces la ruta absoluta en mcp_config.json.
- Asegúrate de que ejecutaste npm run build correctamente y de que la carpeta dist existe.
- Intenta ejecutar el comando desde mcp_config.json manualmente en tu terminal: node /PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js. Busca cualquier error que se muestre.
- Consulta los registros de Claude Desktop (consulta la guía oficial de depuración de MCP).
- Asegúrate de que todos los mensajes de estado console.log en el código del servidor se cambiaron a console.error.
Errores de Autorización de Google:
- Asegúrate de haber habilitado las API correctas (Docs, Drive).
- Asegúrate de haber añadido tu correo electrónico como Usuario de Prueba en la Pantalla de Consentimiento de OAuth.
- Verifica que el archivo credentials.json esté colocado correctamente en la raíz del proyecto.

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles. (Nota: Deberías añadir un archivo LICENSE que contenga el texto de la Licencia MIT a tu repositorio).