Google Sheets

🤔 ¿Qué es esto?

mcp-google-sheets es un servidor MCP basado en Python que actúa como un puente entre cualquier cliente compatible con MCP (como Claude Desktop) y la API de Google Sheets. Te permite interactuar con tus hojas de cálculo de Google utilizando un conjunto definido de herramientas, habilitando potentes flujos de trabajo de automatización y manipulación de datos impulsados por IA.

🚀 Inicio rápido (usando uvx)

Esencialmente, el servidor se ejecuta en una línea: uvx mcp-google-sheets@latest.

Este comando descargará automáticamente el código más reciente y lo ejecutará. Recomendamos usar siempre @latest para asegurarte de tener la versión más nueva con las últimas funciones y correcciones de errores.

Consulta la Guía de referencia de IDs para obtener más información sobre los IDs utilizados a continuación.

1. ☁️ Requisito previo: Configuración de Google Cloud

   • Debes configurar las credenciales de Google Cloud Platform y habilitar las API necesarias primero. Recomendamos encarecidamente usar una Cuenta de servicio.
   • ➡️ Salta a la guía de Configuración detallada de Google Cloud Platform a continuación.

2. 🐍 Instalar uv

   • uvx es parte de uv, un instalador y resolvedor de paquetes de Python rápido. 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
     

     Sigue las instrucciones en la salida del instalador para agregar uv a tu PATH si es necesario.

3. 🔑 Establecer variables de entorno esenciales (se recomienda 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"
     

   • (CMD de Windows)

     set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json"
     set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
     

   • (PowerShell de Windows)

     $env:SERVICE_ACCOUNT_PATH = "C:\path\to\your\service-account-key.json"
     $env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID"
     

   • ➡️ Consulta 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@latest
     

   • El servidor se iniciará e imprimirá registros indicando que está listo.

   • 💡 Consejo profesional: Usa siempre @latest para asegurarte de obtener la versión más nueva con correcciones de errores y funciones. Sin @latest, uvx puede usar una versión anterior en caché.

5. 🔌 Conecta tu cliente MCP

   • Configura tu 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 porque el cliente puede iniciar el servidor por ti. Pero es una buena práctica probar el paso 4 de todos modos para asegurarte de que todo esté configurado correctamente.
   • ➡️ Consulta Uso con Claude Desktop para ver ejemplos.

6. ⚡ Opcional: Habilitar el filtrado de herramientas (reducir el uso de contexto)

   • De forma predeterminada, las 19 herramientas están habilitadas (~13K tokens). Para reducir el uso de contexto, habilita solo las herramientas que necesites.
   • ➡️ Consulta Filtrado de herramientas para obtener detalles.

¡Estás listo! Comienza a emitir comandos a través de tu cliente MCP.

✨ Características clave

• 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 mediante variables de entorno.
• Implementación fácil: Ejecuta al instante con uvx (sensación de cero instalación) o clona para desarrollo usando uv.
• Listo para IA: Diseñado para su uso con clientes compatibles con MCP, lo que permite la interacción con hojas de cálculo en lenguaje natural.
• Filtrado de herramientas: Reduce el uso de la ventana de contexto habilitando solo las herramientas que necesitas con la variable de entorno --include-tools o ENABLED_TOOLS.

🎯 Filtrado de herramientas (reducir el uso de contexto)

Problema: De forma predeterminada, este servidor MCP expone las 19 herramientas, consumiendo ~13,000 tokens antes de que comience cualquier conversación. Si solo necesitas algunas herramientas, esto desperdicia un valioso espacio en la ventana de contexto.

Solución: Usa el filtrado de herramientas para habilitar solo las herramientas que realmente usas.

Cómo habilitar el filtrado de herramientas

Puedes filtrar herramientas usando cualquiera de las siguientes opciones:

1. Argumento de línea de comandos --include-tools:

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": [
           "mcp-google-sheets@latest",
           "--include-tools",
           "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         ],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json"
         }
       }
     }
   }
   

2. Variable de entorno ENABLED_TOOLS:

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": ["mcp-google-sheets@latest"],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json",
           "ENABLED_TOOLS": "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         }
       }
     }
   }
   

Nombres de herramientas disponibles

Al filtrar, usa estos nombres de herramientas exactos (separados por comas, sin espacios):

Herramientas más comunes (subconjunto recomendado):

• get_sheet_data - Leer de hojas de cálculo
• update_cells - Escribir en hojas de cálculo
• list_spreadsheets - Buscar hojas de cálculo
• list_sheets - Navegar por pestañas

Todas las herramientas disponibles:

• add_columns
• add_rows
• batch_update
• batch_update_cells
• copy_sheet
• create_sheet
• create_spreadsheet
• find_in_spreadsheet
• get_multiple_sheet_data
• get_multiple_spreadsheet_summary
• get_sheet_data
• get_sheet_formulas
• list_folders
• list_sheets
• list_spreadsheets
• rename_sheet
• search_spreadsheets
• share_spreadsheet
• update_cells

Nota: Si no se especifican ni --include-tools ni ENABLED_TOOLS, todas las herramientas están habilitadas (comportamiento predeterminado).

🛠️ Herramientas y recursos disponibles

Este servidor expone las siguientes herramientas para interactuar con Google Sheets:

Consulta la Guía de referencia de IDs para obtener más información sobre los IDs utilizados a continuación.

(Los parámetros de entrada son típicamente cadenas a menos que se especifique lo contrario)

• list_spreadsheets: Lista las hojas de cálculo en la carpeta configurada de Drive (Cuenta de Servicio) o accesibles por el usuario (OAuth).
  • folder_id (cadena opcional): ID de la carpeta de Google Drive para buscar. Se obtiene de su URL. Si se omite, usa la carpeta predeterminada configurada o busca en 'Mi Drive'.
  • Devuelve: Lista de objetos [{id: string, title: string}]
• create_spreadsheet: Crea una nueva hoja de cálculo.
  • title (cadena): El título deseado para la hoja de cálculo. Ejemplo: "Informe Trimestral Q4".
  • folder_id (cadena opcional): ID de la carpeta de Google Drive donde se debe crear la hoja de cálculo. Se obtiene de su URL. Si se omite, usa la carpeta predeterminada configurada o la raíz.
  • Devuelve: Objeto con información de la hoja de cálculo, incluyendo spreadsheetId, title y folder.
• get_sheet_data: Lee datos de un rango en una hoja/pestaña.
  • spreadsheet_id (cadena): El ID de la hoja de cálculo (de su URL).
  • sheet (cadena): Nombre de la hoja/pestaña (ej., "Hoja1").
  • range (cadena opcional): Notación A1 (ej., 'A1:C10', 'Sheet1!B2:D'). Si se omite, lee toda la hoja/pestaña especificada por sheet.
  • include_grid_data (booleano opcional, predeterminado False): Si es True, devuelve datos completos de la cuadrícula, incluyendo formato y metadatos (mucho más grande). Si es False, devuelve solo valores (más eficiente).
  • Devuelve: Si es include_grid_data=True, datos completos de la cuadrícula con metadatos (respuesta get). Si es False, un objeto de resultado de valores de la API de Valores (respuesta values.get).
• get_sheet_formulas: Lee fórmulas de un rango en una hoja/pestaña.
  • spreadsheet_id (cadena): El ID de la hoja de cálculo (de su URL).
  • sheet (cadena): Nombre de la hoja/pestaña (ej., "Hoja1").
  • range (cadena opcional): Notación A1 (ej., 'A1:C10', 'Sheet1!B2:D'). Si se omite, lee todas las fórmulas en la hoja/pestaña especificada por sheet.
  • Devuelve: Matriz 2D de fórmulas de celdas (matriz de matrices) (respuesta values.get).
• update_cells: Escribe datos en un rango específico. Sobrescribe datos existentes.
  • spreadsheet_id (cadena): El ID de la hoja de cálculo (de su URL).
  • sheet (cadena): Nombre de la hoja/pestaña (ej., "Hoja1").
  • range (cadena): Rango en notación A1 para escribir (ej., 'A1:C3').
  • data (matriz de matrices): Matriz 2D de valores a escribir. Ejemplo: [[1, 2, 3], ["a", "b", "c"]].
  • Devuelve: Objeto de resultado de actualización (respuesta values.update).
• batch_update_cells: Actualiza múltiples rangos en una sola llamada a la API.
  • spreadsheet_id (cadena): El ID de la hoja de cálculo (de su URL).
  • sheet (cadena): Nombre de la hoja/pestaña (ej., "Hoja1").
  • ranges (objeto): Diccionario que mapea cadenas de rango (notación A1) a matrices 2D de valores. Ejemplo: { "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] }.
  • Devuelve: Resultado de la operación (respuesta values.batchUpdate).
• add_rows: Agrega (inserta) filas vacías a una hoja/pestaña en un índice especificado.
  • spreadsheet_id (cadena): El ID de la hoja de cálculo (de su URL).
  • sheet (cadena): Nombre de la hoja/pestaña (ej., "Hoja1").
  • count (entero): Número de filas vacías a insertar.
  • start_row (entero opcional, predeterminado 0): Índice de fila basado en 0 para comenzar a insertar filas. Si se omite, se predetermina a 0 (inserta al principio).
  • Devuelve: Resultado de la operación (respuesta batchUpdate).
• list_sheets: Lista todos los nombres de hojas/pestañas dentro de una hoja de cálculo.
  • spreadsheet_id (cadena): El ID de la hoja de cálculo (de su URL).
  • Devuelve: Lista de cadenas de nombres de hojas/pestañas. Ejemplo: ["Sheet1", "Sheet2"].
• create_sheet: Agrega una nueva hoja/pestaña a una hoja de cálculo.
  • spreadsheet_id (cadena): El ID de la hoja de cálculo (de su URL).
  • title (cadena): Nombre para la nueva hoja/pestaña.
  • Devuelve: Objeto de propiedades de la nueva hoja.
• get_multiple_sheet_data: Obtiene datos de múltiples rangos en potencialmente diferentes hojas de cálculo en una sola llamada.
  • queries (matriz de objetos): Cada objeto necesita spreadsheet_id, sheet y range. Ejemplo: [{"spreadsheet_id": "abc", "sheet": "Sheet1", "range": "A1:B2"}, ...].
  • Devuelve: Lista de objetos, cada uno conteniendo los parámetros de consulta y el data obtenido o un error. Cada data es una respuesta values.get.
• get_multiple_spreadsheet_summary: Obtiene títulos, nombres de hojas/pestañas, encabezados y primeras filas para múltiples hojas de cálculo.
  • spreadsheet_ids (matriz de cadenas): IDs de las hojas de cálculo (de sus URLs).
  • rows_to_fetch (entero opcional, predeterminado 5): Cuántas filas (incluyendo encabezado) previsualizar. Ejemplo: 5.
  • Devuelve: Lista de objetos de resumen para cada hoja de cálculo.
• share_spreadsheet: Comparte una hoja de cálculo con usuarios/correos y roles especificados.
  • spreadsheet_id (cadena): El ID de la hoja de cálculo (de su URL).
  • recipients (matriz de objetos): [{"email_address": "user@example.com", "role": "writer"}, ...]. Roles: reader, commenter, writer.
  • send_notification (booleano opcional, predeterminado True): Enviar notificaciones por correo a los destinatarios.
  • Devuelve: Diccionario con listas de successes y failures.
• add_columns: Agrega (inserta) columnas vacías a una hoja/pestaña en un índice especificado.
  • spreadsheet_id (cadena): El ID de la hoja de cálculo (de su URL).
  • sheet (cadena): Nombre de la hoja/pestaña (ej., "Hoja1").
  • count (entero): Número de columnas vacías a insertar.
  • start_column (entero opcional, predeterminado 0): Índice de columna basado en 0 para comenzar a insertar. Si se omite, se predetermina a 0 (inserta al principio).
  • Devuelve: Resultado de la operación (respuesta batchUpdate).
• copy_sheet: Duplica una hoja/pestaña de una hoja de cálculo a otra y opcionalmente la renombra.
  • src_spreadsheet (cadena): ID de la hoja de cálculo de origen (de su URL).
  • src_sheet (cadena): Nombre de la hoja/pestaña de origen (ej., "Hoja1").
  • dst_spreadsheet (cadena): ID de la hoja de cálculo de destino (de su URL).
  • dst_sheet (cadena): Nombre deseado de la hoja/pestaña en la hoja de cálculo de destino.
  • Devuelve: Resultado de las operaciones de copia y renombrado opcional.
• rename_sheet: Renombra una hoja/pestaña existente.
  • spreadsheet (cadena): El ID de la hoja de cálculo (de su URL).
  • sheet (cadena): Nombre actual de la hoja/pestaña (ej., "Hoja1").
  • new_name (cadena): Nuevo nombre de la hoja/pestaña (ej., "Transacciones").
  • Devuelve: Resultado de la operación (respuesta batchUpdate).
• add_chart: Crea un gráfico en una hoja de cálculo de Google a partir de datos especificados.
  • spreadsheet_id (cadena): El ID de la hoja de cálculo (de su URL).
  • sheet (cadena): Nombre de la hoja/pestaña que contiene los datos (ej., "Hoja1").
  • chart_type (cadena): Tipo de gráfico a crear. Opciones: COLUMN (barras verticales), BAR (barras horizontales), LINE, AREA, PIE, SCATTER, COMBO, HISTOGRAM.
  • data_range (cadena): Rango en notación A1 para los datos del gráfico (ej., "A1:C10"). La primera fila se trata como encabezados.
  • title (cadena opcional): Título del gráfico.
  • x_axis_label (cadena opcional): Etiqueta para el eje X (eje inferior). No aplicable para gráficos circulares.
  • y_axis_label (cadena opcional): Etiqueta para el eje Y (eje izquierdo). No aplicable para gráficos circulares.
  • position_x (entero opcional, predeterminado 0): Desplazamiento de posición horizontal en píxeles desde la esquina superior izquierda.
  • position_y (entero opcional, predeterminado 0): Desplazamiento de posición vertical en píxeles desde la esquina superior izquierda.
  • width (entero opcional, predeterminado 600): Ancho del gráfico en píxeles.
  • height (entero opcional, predeterminado 400): Alto del gráfico en píxeles.
  • Devuelve: Objeto de resultado con estado de éxito, ID del gráfico y detalles de la operación.

Recursos 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 requerida antes de ejecutar el servidor.

1. Crear/Seleccionar un Proyecto GCP: Vaya a la Consola de Google Cloud.
2. Habilitar APIs: Navegue a "APIs y Servicios" -> "Biblioteca". Busque y habilite:
   • Google Sheets API
   • Google Drive API
3. Configurar Credenciales: Debe elegir un método de autenticación a continuación (se recomienda Cuenta de Servicio).

🔑 Autenticación y Variables de Entorno (Detallada)

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

Consulte la Guía de Referencia de IDs para más información sobre los IDs utilizados a continuación.

Método A: Cuenta de Servicio (Recomendado para Servidores/Automatización) ✅

• ¿Por qué? Sin interfaz gráfica (no se necesita navegador), seguro, ideal para entornos de servidor. No expira fácilmente.
• Pasos:
  1. Crear Cuenta de Servicio: En la Consola GCP -> "IAM y Administración" -> "Cuentas de Servicio".
     • Haga clic en "+ CREAR CUENTA DE SERVICIO". Asígnele un nombre (ej., mcp-sheets-service).
     • Otorgue Roles: Agregue el rol Editor para 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.
     • Haga clic en "Listo". Encuentre la cuenta, haga clic en Acciones (⋮) -> "Administrar claves".
     • Haga clic en "AGREGAR CLAVE" -> "Crear clave nueva" -> JSON -> "CREAR".
     • Descargue y almacene de forma segura el archivo de clave JSON.
  2. Crear y Compartir Carpeta de Google Drive:
     • En Google Drive, cree una carpeta (ej., "Hojas Administradas por IA").
     • 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 de la Cuenta de Servicio (del archivo JSON client_email).
     • Otorgue acceso de Editor. Desmarque "Notificar a las personas". Haga clic en "Compartir".
  3. Configurar 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. (Consulte Inicio Ultra Rápido para ejemplos específicos por sistema operativo)

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

• ¿Por qué? Para uso personal o desarrollo local donde el inicio de sesión interactivo en el navegador es aceptable.
• Pasos:
  1. Configurar Pantalla de Consentimiento OAuth: En la Consola GCP -> "APIs y Servicios" -> "Pantalla de consentimiento de OAuth". Seleccione "Externo", complete la información requerida, agregue alcances (.../auth/spreadsheets, .../auth/drive), agregue usuarios de prueba si es necesario.
  2. Crear ID de Cliente OAuth: En la Consola GCP -> "APIs y Servicios" -> "Credenciales". "+ CREAR CREDENCIALES" -> "ID de cliente de OAuth" -> Tipo: Aplicación de escritorio. Asígnele un nombre. "CREAR". Descargue el JSON.
  3. Configurar Variables de Entorno:
     • CREDENTIALS_PATH: Ruta al archivo JSON de credenciales OAuth descargado (predeterminado: credentials.json).
     • TOKEN_PATH: Ruta para almacenar el token de actualización del usuario después del primer inicio de sesión (predeterminado: token.json). Debe ser escribible.

Método C: Inyección Directa de Credenciales (Avanzado) 🔒

• ¿Por qué? Útil en entornos como Docker, Kubernetes o CI/CD donde gestionar archivos es difícil, pero las variables de entorno son fáciles/seguras. Evita el acceso al sistema de archivos.
• ¿Cómo? En lugar de proporcionar una ruta al archivo de credenciales, proporcionas el contenido del archivo, codificado en Base64, directamente en una variable de entorno.
• Pasos:
  1. Obtén tu archivo JSON de credenciales (ya sea clave de cuenta de servicio o archivo de ID de cliente OAuth). Llamémoslo your_credentials.json.
  2. Genera 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): Evita pegar credenciales sensibles en codificadores en línea no confiables.
  3. Configura la variable de entorno:
     • CREDENTIALS_CONFIG: Establece esta variable a la cadena Base64 completa que acabas de generar.

       # Example (Linux/macOS) - Use the actual string generated
       export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."
       

Método D: Credenciales predeterminadas de la aplicación (ADC) 🌐

• ¿Por qué? Ideal para entornos de Google Cloud (GKE, Compute Engine, Cloud Run) y desarrollo local con gcloud auth application-default login. No se necesitan archivos de credenciales explícitos.
• ¿Cómo? Utiliza la cadena de Credenciales predeterminadas de la aplicación de Google para descubrir automáticamente credenciales de múltiples fuentes.
• Orden de búsqueda de ADC:
  1. Variable de entorno GOOGLE_APPLICATION_CREDENTIALS (ruta a la clave de cuenta de servicio) - variable estándar de Google
  2. Credenciales de gcloud auth application-default login (desarrollo local)
  3. Cuenta de servicio adjunta desde el servidor de metadatos (GKE, Compute Engine, etc.)
• Configuración:
  • Desarrollo local:
    1. Ejecuta gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive una vez
    2. Configura un proyecto de cuota: gcloud auth application-default set-quota-project <project_id> (reemplaza <project_id> con tu ID de proyecto de Google Cloud)
  • Google Cloud: Adjunta una cuenta de servicio a tu recurso de cómputo
  • Variable de entorno: Configura GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json (estándar de Google)
• No se necesitan variables de entorno adicionales - ADC se usa automáticamente como respaldo cuando otros métodos fallan.

Nota: GOOGLE_APPLICATION_CREDENTIALS es la variable de entorno estándar oficial de Google, mientras que SERVICE_ACCOUNT_PATH es específica de este servidor MCP. Si configuras GOOGLE_APPLICATION_CREDENTIALS, ADC la encontrará automáticamente.

Prioridad de autenticación y resumen

El servidor verifica las credenciales en este orden:

1. CREDENTIALS_CONFIG (contenido Base64)
2. SERVICE_ACCOUNT_PATH (ruta al JSON de cuenta de servicio)
3. CREDENTIALS_PATH (ruta al JSON de OAuth) - activa el flujo interactivo si el token falta o expira
4. Credenciales predeterminadas de la aplicación (ADC) - respaldo automático

Resumen de variables de entorno:

⚙️ Ejecución del servidor (detallado)

Consulta la Guía de referencia de ID para obtener más información sobre los ID utilizados a continuación.

Método 1: Usando uvx (Recomendado para usuarios)

Como se muestra en la Guía de inicio ultra rápido, esta es la forma más fácil. Configura las variables de entorno y luego ejecuta:

uvx mcp-google-sheets@latest

uvx se encarga de obtener y ejecutar el paquete temporalmente.

Método 2: Para desarrollo (clonando el repositorio)

Si deseas modificar el código:

1. Clonar: git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets (Usa la URL real)
2. Configurar variables de entorno: Como se describió anteriormente.
3. Ejecutar usando uv: (Usa el código local)

   uv run mcp-google-sheets
   # Or via the script name if defined in pyproject.toml, e.g.:
   # uv run start
   

Método 3: Docker (transporte SSE)

Ejecuta el servidor en un contenedor usando el Dockerfile incluido:

# Build the image
docker build -t mcp-google-sheets .

# Run (SSE on port 8000)
# NOTE: Prefer CREDENTIALS_CONFIG (Base64 credentials content) in containers.
docker run --rm -p 8000:8000 ^
  -e HOST=0.0.0.0 ^
  -e PORT=8000 ^
  -e CREDENTIALS_CONFIG=YOUR_BASE64_CREDENTIALS ^
  -e DRIVE_FOLDER_ID=YOUR_DRIVE_FOLDER_ID ^
  mcp-google-sheets

• Usa CREDENTIALS_CONFIG en lugar de SERVICE_ACCOUNT_PATH dentro de Docker para evitar montar secretos como archivos.
• El contenedor inicia con --transport sse y escucha en HOST/PORT. Apunta tu cliente MCP a http://localhost:8000 usando transporte SSE.

🔌 Uso con Claude Desktop

Agrega la configuración del servidor a claude_desktop_config.json bajo mcpServers. Elige el bloque que coincida con tu configuración:

Consulta la Guía de referencia de ID para obtener más información sobre los ID utilizados a continuación.

⚠️ Notas importantes:

• 🍎 Usuarios de macOS: usa la ruta completa: "/Users/yourusername/.local/bin/uvx" en lugar de solo "uvx"

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "/Users/yourusername/.local/bin/uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "CREDENTIALS_PATH": "/full/path/to/your/credentials.json",
        "TOKEN_PATH": "/full/path/to/your/token.json"
      }
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "CREDENTIALS_CONFIG": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "mcp-google-sheets-local": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/mcp-google-sheets",
        "mcp-google-sheets"
      ],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/path/to/your/mcp-google-sheets/service_account.json",
        "DRIVE_FOLDER_ID": "your_drive_folder_id_here"
      }
    }
  }
}

💬 Ejemplos de prompts para Claude

Una vez conectado, prueba prompts como:

• "Lista todas las hojas de cálculo a las que tengo acceso." (o "en mi carpeta AI Managed Sheets")
• "Crea una nueva hoja de cálculo titulada 'Informe de ventas trimestral Q3 2024'."
• "En la hoja de cálculo 'Informe de ventas trimestral', obtén los datos de Sheet1 en el rango A1 a E10."
• "Agrega 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', actualiza la celda B2 a 'En progreso'."
• "Agrega 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']]"
• "Obtén un resumen de las hojas de cálculo 'Datos de ventas' e 'Inventario'."
• "Comparte la hoja de cálculo 'Horario de vacaciones del equipo' con team@example.com como lector y manager@example.com como escritor. No envíes notificaciones."
• "Crea un gráfico de columnas en mi hoja de cálculo 'Informe de ventas' que muestre los ingresos mensuales a partir de los datos en el rango A1:B13."
• "Agrega un gráfico circular a la hoja 'Análisis de mercado' con datos de A1:B5 titulado 'Participación de mercado por producto'."
• "En la hoja de cálculo abc123, crea un gráfico de líneas en Sheet1 desde el rango A1:C10 con el título 'Tendencias de crecimiento' y etiquetas 'Mes' e 'Ingresos'."

🆔 Guía de referencia de ID

Usa la siguiente guía de referencia para encontrar los diversos ID mencionados en la documentación:

Google Cloud Project ID:
  https://console.cloud.google.com/apis/dashboard?project=sheets-mcp-server-123456
                                                          └───── Project ID ─────┘

Google Drive Folder ID:
  https://drive.google.com/drive/u/0/folders/1xcRQCU9xrNVBPTeNzHqx4hrG7yR91WIa
                                             └────────── Folder ID ──────────┘

Google Sheets Spreadsheet ID:
  https://docs.google.com/spreadsheets/d/25_-_raTaKjaVxu9nJzA7-FCrNhnkd3cXC54BPAOXemI/edit
                                         └───────────── Spreadsheet ID ─────────────┘

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Abre un issue para discutir errores o solicitudes de funciones. Se agradecen las solicitudes de extracción (pull requests).

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.

🙏 Créditos

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