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.

Related MCP server: Spreadsheet MCP Server

🚀 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 mcp-google-sheets

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:

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets"],
      "env": {
        // Use ABSOLUTE paths here
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      },
      "healthcheck_url": "http://localhost:8000/health" // Adjust host/port if needed
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets"],
      "env": {
        // Use ABSOLUTE paths here
        "CREDENTIALS_PATH": "/full/path/to/your/credentials.json",
        "TOKEN_PATH": "/full/path/to/your/token.json" // Ensure this path is writable
      },
      "healthcheck_url": "http://localhost:8000/health"
    }
  }
}

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

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets"],
      "env": {
        // Paste the full Base64 string here
        "CREDENTIALS_CONFIG": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here" // Still needed for Service Account folder context
      },
      "healthcheck_url": "http://localhost:8000/health"
    }
  }
}

{
  "mcpServers": {
    "mcp-google-sheets-dev": { // Use a distinct name
      "command": "uv",
      "args": ["run", "mcp-google-sheets"], // Assumes `mcp-google-sheets` script exists
      "cwd": "/full/path/to/cloned/mcp-google-sheets", // ABSOLUTE path to repo
      "env": {
        // Choose ONE auth method and set corresponding vars
        // Example: Service Account Path
        "SERVICE_ACCOUNT_PATH": "/full/path/to/cloned/mcp-google-sheets/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      },
      "healthcheck_url": "http://localhost:8000/health",
      "disabled": false
    }
  }
}

💬 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.