mcp-google-sheets

🤔¿Qué es esto?

mcp-google-sheets es un servidor MCP basado en Python que actúa como puente entre cualquier cliente compatible con MCP (como Claude Desktop) y la API de Hojas de Cálculo de Google. Permite interactuar con Hojas de Cálculo de Google mediante un conjunto definido de herramientas, lo que posibilita potentes flujos de trabajo de automatización y manipulación de datos basados en IA.

🚀 Inicio rápido (Usando uvx )

Básicamente, el servidor se ejecuta en una línea: uvx mcp-google-sheets .

Este comando descargará automáticamente el código más reciente si es necesario y lo ejecutará. Sin embargo, configurar Google Cloud requiere varios pasos; lea los pasos a continuación.

1. ☁️ Requisito previo: configuración de Google Cloud
   • Primero debes configurar las credenciales de Google Cloud Platform y habilitar las API necesarias. Recomendamos encarecidamente usar una cuenta de servicio .
   • ➡️ Vaya a la guía de configuración detallada de Google Cloud Platform a continuación.
2. 🐍Instalar uv
   • uvx forma parte de uv , un instalador y solucionador rápido de paquetes de Python. Instálalo si aún no lo has hecho:
     # macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Or using pip: # pip install uv
     Siga las instrucciones en la salida del instalador para agregar uv a su PATH si es necesario.
3. 🔑 Establecer variables de entorno esenciales (se recomienda una cuenta de servicio)
   • Debes indicarle al servidor cómo autenticarse. Configura estas variables en tu terminal:
   • (Linux/macOS)
     # Replace with YOUR actual path and folder ID from the Google Setup step export SERVICE_ACCOUNT_PATH="/path/to/your/service-account-key.json" export DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
   • (Comando de Windows)
     set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json" set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
   • (Windows PowerShell)
     $env:SERVICE_ACCOUNT_PATH = "C:\path\to\your\service-account-key.json" $env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID"
   • ➡️ Consulte Autenticación detallada y variables de entorno para otras opciones (OAuth, CREDENTIALS_CONFIG ).
4. 🏃 ¡Ejecuta el servidor!
   • uvx descargará y ejecutará automáticamente la última versión de mcp-google-sheets :
     uvx mcp-google-sheets
   • El servidor se iniciará e imprimirá registros indicando que está listo.
5. 🔌 Conecte su cliente MCP
   • Configure su cliente (por ejemplo, Claude Desktop) para conectarse al servidor en ejecución.
   • Dependiendo del cliente que uses, es posible que no necesites el paso 4, ya que el cliente puede iniciar el servidor automáticamente. Sin embargo, es recomendable probar el paso 4 de todas formas para asegurarte de que todo esté configurado correctamente.
   • ➡️ Consulte Uso con Claude Desktop para ver ejemplos.

¡Listo! Empieza a enviar comandos a través de tu cliente MCP.

✨ Características principales

• Integración perfecta: se conecta directamente a las API de Google Drive y Google Sheets.
• Herramientas integrales: Ofrece una amplia gama de operaciones (CRUD, listado, procesamiento por lotes, uso compartido, formato, etc.).
• Autenticación flexible: admite cuentas de servicio (recomendado) , OAuth 2.0 e inyección directa de credenciales a través de variables de entorno.
• Implementación fácil: Ejecútelo instantáneamente con uvx (sensación de instalación cero) o clone para desarrollo usando uv .
• Listo para IA: diseñado para usarse con clientes compatibles con MCP, lo que permite la interacción con hojas de cálculo en lenguaje natural.

🛠️ Herramientas y recursos disponibles

Este servidor expone las siguientes herramientas para interactuar con Hojas de cálculo de Google:

(Los parámetros de entrada suelen ser cadenas a menos que se especifique lo contrario)

• list_spreadsheets : enumera las hojas de cálculo en la carpeta de Drive configurada (cuenta de servicio) o a la que puede acceder el usuario (OAuth).
  • Devuelve: Lista de objetos [{id: string, title: string}]
• create_spreadsheet : crea una nueva hoja de cálculo.
  • title (cadena): el título deseado.
  • Devuelve: Objeto con información de la hoja de cálculo, incluido spreadsheetId .
• get_sheet_data : lee datos de un rango en una hoja.
  • spreadsheet_id (cadena)
  • sheet (cadena): Nombre de la hoja.
  • range (cadena opcional): notación A1 (p. ej., 'A1:C10' , 'Sheet1!B2:D' ). Si se omite, se lee toda la hoja.
  • Devuelve: matriz 2D de valores de celda.
• update_cells : Escribe datos en un rango específico. Sobrescribe los datos existentes.
  • spreadsheet_id (cadena)
  • sheet (cadena)
  • range (cadena): notación A1.
  • data (matriz 2D): Valores a escribir.
  • Devuelve: Actualizar el objeto de resultado.
• batch_update_cells : actualiza múltiples rangos en una llamada API.
  • spreadsheet_id (cadena)
  • sheet (cadena)
  • ranges (objeto): Diccionario que asigna cadenas de rango (notación A1) a matrices 2D de valores { "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] } .
  • Devuelve: Objeto de resultado de actualización por lotes.
• add_rows : agrega filas al final de una hoja (después de la última fila con datos).
  • spreadsheet_id (cadena)
  • sheet (cadena)
  • data (matriz 2D): filas para agregar.
  • Devuelve: Actualizar el objeto de resultado.
• list_sheets : enumera todos los nombres de hojas dentro de una hoja de cálculo.
  • spreadsheet_id (cadena)
  • Devuelve: Lista de cadenas de nombres de hojas ["Sheet1", "Sheet2"] .
• create_sheet : agrega una nueva hoja (pestaña) a una hoja de cálculo.
  • spreadsheet_id (cadena)
  • title (cadena): nombre de la nueva hoja.
  • Devuelve: Nuevo objeto de propiedades de hoja.
• get_multiple_sheet_data : obtiene datos de múltiples rangos en hojas de cálculo potencialmente diferentes en una sola llamada.
  • queries (matriz de objetos): cada objeto necesita spreadsheet_id , sheet y range . [{spreadsheet_id: 'abc', sheet: 'Sheet1', range: 'A1:B2'}, ...] .
  • Devuelve: Lista de objetos, cada uno de los cuales contiene los parámetros de consulta y data obtenidos o un error .
• get_multiple_spreadsheet_summary : obtiene títulos, nombres de hojas, encabezados y las primeras filas de varias hojas de cálculo.
  • spreadsheet_ids (matriz de cadenas)
  • rows_to_fetch (entero opcional, predeterminado 5): cuántas filas (incluido el encabezado) se previsualizarán.
  • Devuelve: Lista de objetos de resumen para cada hoja de cálculo.
• share_spreadsheet : comparte una hoja de cálculo con usuarios, correos electrónicos y roles específicos.
  • spreadsheet_id (cadena)
  • recipients (matriz de objetos): [{email_address: 'user@example.com', role: 'writer'}, ...] . Roles: reader , commenter , writer .
  • send_notification (booleano opcional, predeterminado Verdadero): envía notificaciones por correo electrónico.
  • Devuelve: Diccionario con listas de successes y failures .
• add_columns : Agrega columnas a una hoja. (Verificar los parámetros si están implementados)
• copy_sheet : Duplica una hoja dentro de una hoja de cálculo. (Verificar los parámetros si están implementados)
• rename_sheet : Renombra una hoja existente. (Verificar los parámetros si están implementados)

Recursos del MCP:

• spreadsheet://{spreadsheet_id}/info : obtiene metadatos básicos sobre una hoja de cálculo de Google.
  • Devuelve: cadena JSON con información de la hoja de cálculo.

Configuración de Google Cloud Platform (detallada)

Esta configuración es necesaria antes de ejecutar el servidor.

1. Crear o seleccionar un proyecto de GCP: vaya a la consola de Google Cloud .
2. Habilitar API: Vaya a "API y Servicios" -> "Biblioteca". Busque y habilite:
   • Google Sheets API
   • Google Drive API
3. Configurar credenciales: debe elegir uno de los métodos de autenticación a continuación (se recomienda una cuenta de servicio).

🔑 Autenticación y variables de entorno (detalladas)

El servidor necesita credenciales para acceder a las API de Google. Elija un método:

Método A: Cuenta de servicio (recomendado para servidores/automatización) ✅

• ¿Por qué? Sin interfaz gráfica (no requiere navegador), seguro, ideal para entornos de servidor. No caduca fácilmente.
• Pasos:
  1. Crear una cuenta de servicio: en GCP Console -> "IAM y administrador" -> "Cuentas de servicio".
     • Haz clic en "+ CREAR CUENTA DE SERVICIO". Asígnale un nombre (p. ej., mcp-sheets-service ).
     • Otorgar roles: agregue el rol Editor para un acceso amplio, o roles más granulares (como roles/drive.file y roles específicos de Hojas de cálculo) para permisos más estrictos.
     • Haz clic en "Listo". Busca la cuenta y haz clic en Acciones (⋮) -> "Administrar claves".
     • Haga clic en "AGREGAR CLAVE" -> "Crear nueva clave" -> JSON -> "CREAR".
     • Descargue y almacene de forma segura el archivo de clave JSON.
  2. Crear y compartir una carpeta de Google Drive:
     • En Google Drive , cree una carpeta (por ejemplo, "Hojas administradas por AI").
     • Anote el ID de la carpeta de la URL: https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID .
     • Haga clic derecho en la carpeta -> "Compartir" -> "Compartir".
     • Ingrese el correo electrónico de la cuenta de servicio (del archivo JSON client_email ).
     • Otorgar acceso al editor . Desmarcar la opción "Notificar". Hacer clic en "Compartir".
  3. Establecer variables de entorno:
     • SERVICE_ACCOUNT_PATH : Ruta completa al archivo de clave JSON descargado.
     • DRIVE_FOLDER_ID : El ID de la carpeta compartida de Google Drive. (Consulta la Guía rápida para ver ejemplos específicos del sistema operativo).

Método B: OAuth 2.0 (Interactivo/Uso personal) 🧑‍💻

• ¿Por qué? Para uso personal o desarrollo local donde se permite el inicio de sesión interactivo mediante navegador.
• Pasos:
  1. Configurar la pantalla de consentimiento de OAuth: En GCP Console -> "APIs y servicios" -> "Pantalla de consentimiento de OAuth". Seleccione "Externo", complete la información requerida, agregue ámbitos ( .../auth/spreadsheets , .../auth/drive ) y agregue usuarios de prueba si es necesario.
  2. Crear ID de cliente de OAuth: En la consola de GCP -> "API y servicios" -> "Credenciales". "+ CREAR CREDENCIALES" -> "ID de cliente de OAuth" -> Tipo: Aplicación de escritorio . Nombre: "CREAR". Descargue el archivo JSON .
  3. Establecer variables de entorno:
     • CREDENTIALS_PATH : Ruta al archivo JSON de credenciales de OAuth descargado (predeterminado: credentials.json ).
     • TOKEN_PATH : Ruta donde se almacena el token de actualización del usuario tras el primer inicio de sesión (predeterminado: token.json ). Debe tener permisos de escritura.

Método C: Inyección directa de credenciales (avanzado) 🔒

• ¿Por qué? Útil en entornos como Docker, Kubernetes o CI/CD, donde la gestión de archivos es compleja, pero las variables de entorno son fáciles y seguras. Evita el acceso al sistema de archivos.
• ¿Cómo? En lugar de proporcionar una ruta al archivo de credenciales, se proporciona el contenido del archivo, codificado en Base64, directamente en una variable de entorno.
• Pasos:
  1. Obtén el archivo JSON de tus credenciales (ya sea la clave de la cuenta de servicio o el archivo de ID de cliente de OAuth). Lo llamaremos your_credentials.json .
  2. Generar la cadena Base64:
     • (Linux/macOS): base64 -w 0 your_credentials.json
     • (Windows PowerShell):
       $filePath = "C:\path\to\your_credentials.json"; # Use actual path $bytes = [System.IO.File]::ReadAllBytes($filePath); $base64 = [System.Convert]::ToBase64String($bytes); $base64 # Copy this output
     • (Precaución): Evite pegar credenciales confidenciales en codificadores en línea que no sean confiables.
  3. Establecer la variable de entorno:
     • CREDENTIALS_CONFIG : Establezca esta variable en la cadena Base64 completa que acaba de generar.
       # Example (Linux/macOS) - Use the actual string generated export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."

Prioridad y resumen de autenticación

El servidor comprueba las credenciales en este orden:

1. CREDENTIALS_CONFIG (contenido Base64)
2. SERVICE_ACCOUNT_PATH (Ruta a la cuenta de servicio JSON)
3. CREDENTIALS_PATH (Ruta a OAuth JSON): activa un flujo interactivo si el token falta o ha expirado.

Resumen de variables ambientales:

⚙️ Ejecución del servidor (detallado)

Método 1: Uso de uvx (recomendado para usuarios)

Como se muestra en la Guía de inicio rápido , esta es la forma más sencilla. Configure las variables de entorno y luego ejecute:

uvx se encarga de obtener y ejecutar el paquete temporalmente.

Método 2: Para el desarrollo (clonación del repositorio)

Si desea modificar el código:

1. Clonar: git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets (Usar URL real)
2. Establecer variables de entorno: como se describe arriba.
3. Ejecutar usando uv : (Utiliza el código local)
   uv run mcp-google-sheets # Or via the script name if defined in pyproject.toml, e.g.: # uv run start

🔌 Uso con Claude Desktop

Agregue la configuración del servidor a claude_desktop_config.json en mcpServers . Seleccione el bloque que coincida con su configuración:

(Es posible que un navegador se abra para iniciar sesión en Google la primera vez)

💬 Ejemplos de indicaciones para Claude

Una vez conectado, pruebe indicaciones como:

• "Enumerar todas las hojas de cálculo a las que tengo acceso" (o "en mi carpeta Hojas de cálculo administradas por AI")
• Cree una nueva hoja de cálculo titulada "Informe de ventas trimestral del tercer trimestre de 2024".
• En la hoja de cálculo 'Informe de ventas trimestral', obtenga los datos del rango A1 a E10 de la Hoja 1.
• "Agregue una nueva hoja llamada 'Resumen' a la hoja de cálculo con ID 1aBcDeFgHiJkLmNoPqRsTuVwXyZ ."
• "En mi hoja de cálculo 'Tareas del proyecto', Hoja 'Tareas', actualice la celda B2 a 'En progreso'."
• "Añada estas filas a la hoja 'Registro' en la hoja de cálculo XYZ : [['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']] "
• Obtenga un resumen de las hojas de cálculo 'Datos de ventas' y 'Recuento de inventario'.
• Comparte la hoja de cálculo "Calendario de vacaciones del equipo" con team@example.com como lector y manager@example.com como escritor. No envíes notificaciones.

🤝 Contribuyendo

¡Se agradecen las contribuciones! Abre un problema para comentar errores o solicitudes de funcionalidad. Se agradecen las solicitudes de incorporación de cambios.

📄 Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

🙏 Créditos

• Creado con FastMCP .
• Inspirado por kazz187/mcp-google-spreadsheet .
• Utiliza bibliotecas de cliente Python de la API de Google.