Claude MCP x Google Docs

Servidor MCP de Google Docs definitivo

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

🔥 ¡ Descubre 10 tareas poderosas que puedes realizar con este servidor mejorado!

Este servidor mejorado utiliza el Protocolo de Contexto de Modelo (MCP) y la biblioteca fastmcp para proporcionar herramientas integrales para leer, escribir, formatear y estructurar Documentos de Google. Actúa como un potente puente que permite a asistentes de IA como Claude interactuar con tus documentos mediante programación con funciones avanzadas.

Características:

Acceso a documentos

• Leer documentos: lea contenido con readGoogleDoc (texto sin formato, estructura JSON o Markdown)
• Añadir a documentos: añade texto a los documentos con appendToGoogleDoc
• Insertar texto: coloca texto en posiciones específicas con insertText
• Eliminar contenido: eliminar contenido de un documento con deleteRange

Formato y estilo

• Formato de texto: aplique un estilo enriquecido con applyTextStyle (negrita, cursiva, colores, etc.)
• Formato de párrafo: controle el diseño del párrafo con applyParagraphStyle (alineación, espaciado, etc.)
• Buscar y formatear: Formatear por contenido de texto usando formatMatchingText (soporte heredado)

Estructura del documento

• Tablas: Crear tablas con insertTable
• Saltos de página: Insertar saltos de página con insertPageBreak
• Funciones experimentales: herramientas como fixListFormatting para la detección automática de listas

Integración

• Autenticación de Google: autenticación segura OAuth 2.0
• Compatible con MCP: diseñado para usarse con Claude y otros clientes de MCP

Prerrequisitos

Antes de comenzar, asegúrese de tener:

1. Node.js y npm: Una versión reciente de Node.js (que incluye npm) instalada en tu ordenador. Puedes descargarla desde nodejs.org . (Se recomienda la versión 18 o superior).
2. Git: necesario para clonar este repositorio. ( Descargar Git ).
3. Una cuenta de Google: la cuenta que posee o tiene acceso a los Documentos de Google con los que desea interactuar.
4. Familiaridad con la línea de comandos: comodidad básica al utilizar una terminal o un símbolo del sistema (como Terminal en macOS/Linux o Símbolo del sistema/PowerShell en Windows).
5. Claude Desktop (opcional): si su objetivo es conectar este servidor a Claude, necesitará tener instalada la aplicación Claude Desktop.

Instrucciones de configuración

Siga estos pasos cuidadosamente para poner en funcionamiento su propia instancia del servidor.

Paso 1: Proyecto y credenciales de Google Cloud (¡la parte importante!)

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

1. Accede a la consola de Google Cloud: Abre tu navegador web y accede a la consola de Google Cloud . Es posible que tengas que iniciar sesión con tu cuenta de Google.
2. Crear o seleccionar un proyecto:
   • Si no tiene un proyecto, haga clic en el menú desplegable de proyectos cerca de la parte superior y seleccione "NUEVO PROYECTO". Asígnele un nombre (p. ej., "Mi servidor de documentos MCP") y haga clic en "CREAR".
   • Si tiene proyectos existentes, puede seleccionar uno o crear uno nuevo.
3. Habilitar API: debe activar los servicios de Google específicos que utiliza este servidor.
   • En la barra de búsqueda en la parte superior, escriba "API y servicios" y seleccione "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 buscar archivos o permisos).
4. Pantalla de configuración de consentimiento de OAuth: esta pantalla les dice a los usuarios (generalmente solo a usted) para qué quiere permiso su aplicación.
   • En el menú de la izquierda, haga clic en "API y servicios" -> " Pantalla de consentimiento de OAuth ".
   • Elija el tipo de usuario: seleccione " Externo " y haga clic en "CREAR".
   • Complete la información de la aplicación:
     • Nombre de la aplicación: Asígnele un nombre que los usuarios verán (por ejemplo, "Claude Docs MCP Access").
     • Correo electrónico de soporte al usuario: seleccione su dirección de correo electrónico.
     • Información de contacto del desarrollador: Ingrese su dirección de correo electrónico.
   • Haga clic en " GUARDAR Y CONTINUAR ".
   • Ámbitos: Haga clic en " AGREGAR O ELIMINAR ÁMBITOS ". Busque y agregue 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)
     • Haga clic en " ACTUALIZAR ".
   • Haga clic en " GUARDAR Y CONTINUAR ".
   • Usuarios de prueba: Haga clic en " AÑADIR USUARIOS ". Ingrese la misma dirección de correo electrónico de Google con la que inició sesión. Haga clic en " AÑADIR ". Esto le permitirá usar la aplicación en modo de prueba.
   • Haga clic en " GUARDAR Y CONTINUAR ". Revise el resumen y haga clic en " VOLVER AL PANEL DE CONTROL ".
5. Crear credenciales (¡las claves!):
   • En el menú de la izquierda, haga clic en "API y servicios" -> " Credenciales ".
   • Haga clic en " + CREAR CREDENCIALES " en la parte superior y elija " ID de cliente OAuth ".
   • Tipo de aplicación: seleccione “ Aplicación de escritorio ” en el menú desplegable.
   • Nombre: Asígnele un nombre (por ejemplo, "Cliente de escritorio MCP Docs").
   • Haga clic en " CREAR ".
6. ⬇️ DESCARGAR EL ARCHIVO DE CREDENCIALES: Aparecerá un cuadro con tu ID de cliente. Haz clic en el botón " DESCARGAR JSON ".
   • Guarda este archivo. Probablemente se llamará algo como client_secret_....json .
   • IMPORTANTE: Cambie el nombre del archivo descargado exactamente a credentials.json .
7. ⚠️ ADVERTENCIA DE SEGURIDAD: ¡ Trate este archivo credentials.json como una contraseña! No lo comparta públicamente ni lo publique en GitHub. Cualquiera que tenga este archivo podría hacerse pasar por su aplicación (aunque necesitaría el consentimiento del usuario para acceder a los datos).

Paso 2: Obtener el código del servidor

1. Clonar el repositorio: abra su terminal/símbolo del sistema y ejecute:
   git clone https://github.com/a-bonus/google-docs-mcp.git mcp-googledocs-server
2. Navegar al directorio:
   cd mcp-googledocs-server
3. Colocar credenciales: mueva o copie el archivo credentials.json que descargó y renombró (del Paso 1.6) directamente en esta carpeta mcp-googledocs-server .

Paso 3: Instalar dependencias

Su servidor necesita algunas bibliotecas auxiliares especificadas en el archivo package.json .

1. 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: Construir el código del servidor

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

1. En tu terminal, ejecuta:
   npm run build
   Esto utiliza el compilador 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 debes ejecutar el servidor manualmente una vez para otorgarle permiso para acceder a los datos de tu cuenta de Google. Esto creará un archivo token.json que guardará la concesión de permisos.

1. En su terminal, ejecute el servidor compilado usando node :
   node ./dist/server.js
2. Mira la Terminal: El script imprimirá:
   • Mensajes de estado (como "Intentando autorizar...").
   • Un mensaje "Autorice esta aplicación visitando esta URL:" seguido de una URL larga https://accounts.google.com/...
3. Autorizar en el navegador:
   • Copia la URL larga completa desde la terminal.
   • Pegue la URL en su navegador web y presione Enter.
   • Inicie sesión con la misma cuenta de Google que agregó como usuario de prueba en el paso 1.4.
   • Google mostrará una pantalla solicitando permiso para que tu aplicación ("Claude Docs MCP Access" o similar) acceda a Google Docs/Drive. Revísala y haz clic en " Permitir " o " Otorgar ".
4. Obtenga el código de autorización:
   • Después de hacer clic en Permitir, es probable que su navegador intente redirigir a http://localhost y muestre el error "No se puede acceder a este sitio" . ¡ESTO ES NORMAL!
   • Revisa atentamente la URL en la barra de direcciones de tu navegador. Se verá así http://localhost/?code=4/0Axxxxxxxxxxxxxx&scope=...
   • Copia la cadena larga de caracteres entre code= y la parte &scope . Este es tu código de autorización de un solo uso.
5. Pegar código en la terminal: Regresa a la terminal donde te espera el script ("Introduce el código de esa página aquí:"). Pega el código que acabas de copiar.
6. Presione Enter.
7. ¡Éxito! El script debería imprimir:
   • "¡Autenticación exitosa!"
   • "Token almacenado en .../token.json"
   • Luego terminará de iniciarse y probablemente imprimirá "Esperando conexión de cliente MCP a través de stdio..." o algo similar, y luego saldrá (o puede presionar Ctrl+C para detenerlo).
8. ✅ Verificar: Ahora deberías ver un nuevo archivo llamado token.json en tu carpeta mcp-googledocs-server .
9. ⚠️ ADVERTENCIA DE SEGURIDAD: Este archivo token.json contiene la clave que permite al servidor acceder a tu cuenta de Google sin necesidad de volver a preguntar. Protégelo como si fuera una contraseña. No lo publiques en GitHub. El archivo .gitignore incluido debería impedirlo automáticamente.

Paso 6: Configurar Claude Desktop (opcional)

Si desea utilizar este servidor con Claude Desktop, deberá indicarle a Claude cómo ejecutarlo.

1. Encuentra tu ruta absoluta: necesitas la ruta completa al código del servidor.
   • En tu terminal, asegúrate de que todavía estás dentro del directorio mcp-googledocs-server .
   • Ejecute el comando pwd (en macOS/Linux) o cd (en Windows, solo muestra la ruta).
   • Copie la ruta completa (por ejemplo, /Users/yourname/projects/mcp-googledocs-server o C:\Users\yourname\projects\mcp-googledocs-server ).
2. Localice mcp_config.json : encuentre el archivo de configuración de Claude:
   • macOS: ~/Library/Application Support/Claude/mcp_config.json (Es posible que tengas que usar el menú "Ir" -> "Ir a la carpeta..." del Finder y pegar ~/Library/Application Support/Claude/ )
   • Windows: %APPDATA%\Claude\mcp_config.json (Pegue %APPDATA%\Claude en la barra de direcciones del Explorador de archivos)
   • Linux: ~/.config/Claude/mcp_config.json
   • Si la carpeta Claude o el archivo mcp_config.json no existen, créelos.
3. Editar mcp_config.json : Abra el archivo en un editor de texto. Agregue o modifique la sección mcpServers de la siguiente manera, reemplazando /PATH/TO/YOUR/CLONED/REPO con la ruta absoluta que copió en el paso 6.1 .
   { "mcpServers": { "google-docs-mcp": { "command": "node", "args": [ "/PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js" ], "env": {} } // Add commas here if you have other servers defined } // Other Claude settings might be here }
   • ¡Asegúrese de que la ruta en "args" sea correcta y absoluta!
   • Si el archivo ya existía, fusione cuidadosamente esta entrada con el objeto mcpServers existente. Asegúrese de que el JSON sea válido (¡compruebe las comas!).
4. Guardar mcp_config.json .
5. Reiniciar Claude Desktop: Cierre Claude completamente y vuelva a abrirlo.

Uso con Claude Desktop

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

• "Utilice el servidor google-docs-mcp para leer el documento con ID YOUR_GOOGLE_DOC_ID ."
• "¿Puedes obtener el contenido de Google Doc YOUR_GOOGLE_DOC_ID ?"
• "Añada '¡Esto fue agregado por Claude!' al documento YOUR_GOOGLE_DOC_ID usando la herramienta google-docs-mcp ".

Ejemplos de uso avanzado:

• Estilo de texto : "Use applyTextStyle para que el texto 'Sección importante' aparezca en negrita y rojo (#FF0000) en el documento YOUR_GOOGLE_DOC_ID ".
• Estilo de párrafo : "Use applyParagraphStyle para alinear al centro el párrafo que contiene 'Título aquí' en el documento YOUR_GOOGLE_DOC_ID ".
• Creación de tabla : "Inserte una tabla 3x4 en el índice 500 en el documento YOUR_GOOGLE_DOC_ID usando la herramienta insertTable ".
• Formato heredado : "Use formatMatchingText para encontrar la segunda instancia de 'Project Alpha' y hacerla azul (#0000FF) en el documento YOUR_GOOGLE_DOC_ID ".

Recuerde 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 envíes accidentalmente tus archivos confidenciales 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 para simplificar la configuración. En entornos de producción o con mayor seguridad, considere almacenar este token de forma más segura, como mediante llaveros del sistema, archivos cifrados o servicios dedicados de gestión de secretos.

Solución de problemas

• Claude muestra "Error" o "No se pudo adjuntar":
  • Verifique nuevamente la ruta absoluta en mcp_config.json .
  • Asegúrese de haber ejecutado npm run build correctamente y de que la carpeta dist exista.
  • 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.
  • Verifique los registros de Claude Desktop (consulte la guía de depuración oficial de MCP).
  • Asegúrese de que todos los mensajes de estado console.log en el código del servidor se hayan cambiado a console.error .
• Errores de autorización de Google:
  • Asegúrese de haber habilitado las API correctas (Docs, Drive).
  • Asegúrese de haber agregado su correo electrónico como Usuario de prueba en la pantalla de consentimiento de OAuth.
  • Verifique que el archivo credentials.json esté ubicado correctamente en la raíz del proyecto.

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulte el archivo LICENSE para obtener más información. (Nota: Debe agregar un archivo LICENSE con el texto de la Licencia MIT a su repositorio).