mcp-google-sheet

🤔 ¿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 Google Sheets. Te permite interactuar con tus hojas de cálculo de Google mediante un conjunto definido de herramientas, lo que habilita potentes flujos de automatización y manipulación de datos impulsados por IA.

Related MCP server: mcp-google-sheets

🚀 Inicio rápido (usando uvx)

Básicamente, 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 forma parte de uv, un instalador y resolutor 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 de la salida del instalador para añadir uv a tu PATH si es necesario.

3. 🔑 Establecer las variables de entorno esenciales (se recomienda cuenta de servicio)

   • Debes indicar al servidor cómo autenticarse. Establece 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"

   • (Windows CMD)

     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"

   • ➡️ 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á y mostrará 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, puede que no necesites el paso 4, ya que 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: Habilita el filtrado de herramientas (reduce 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 más detalles.

¡Ya 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 completas: 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 sencilla: Ejecútalo al instante con uvx (sensación de cero instalación) o clona el repositorio 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.

• Filtrado de herramientas: Reduce el uso de la ventana de contexto habilitando solo las herramientas que necesites con --include-tools o la variable de entorno ENABLED_TOOLS.

🎯 Filtrado de herramientas (reduce 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 unas pocas herramientas, esto desperdicia un valioso espacio de la ventana de contexto.

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

Cómo habilitar el filtrado de herramientas

Puedes filtrar herramientas usando:

1. El 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. La 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 herramienta 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 normalmente cadenas de texto, salvo que se indique lo contrario)

• list_spreadsheets: Enumera las hojas de cálculo en la carpeta de Drive configurada (cuenta de servicio) o accesibles por el usuario (OAuth).

  • folder_id (cadena opcional): ID de la carpeta de Google Drive donde buscar. Se obtiene de su URL. Si se omite, usa la carpeta predeterminada configurada o busca en "Mi unidad".

  • 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: "Quarterly Report 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 (p. ej., "Sheet1").

  • range (cadena opcional): Notación A1 (p. 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 los datos completos de la cuadrícula, incluidos formato y metadatos (mucho más grande). Si es False, devuelve solo los valores (más eficiente).

  • Devuelve: Si include_grid_data=True, datos completos de la cuadrícula con metadatos (respuesta de get). Si es False, un objeto de resultado de valores de la API de Values (respuesta de 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 (p. ej., "Sheet1").

  • range (cadena opcional): Notación A1 (p. 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 de values.get).

• update_cells: Escribe datos en un rango específico. Sobrescribe los datos existentes.

  • spreadsheet_id (cadena): El ID de la hoja de cálculo (de su URL).

  • sheet (cadena): Nombre de la hoja/pestaña (p. ej., "Sheet1").

  • range (cadena): Rango en notación A1 donde escribir (p. 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 la actualización (respuesta de values.update).

• batch_update_cells: Actualiza varios 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 (p. ej., "Sheet1").

  • ranges (objeto): Diccionario que asigna 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 de 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 (p. ej., "Sheet1").

  • count (entero): Número de filas vacías a insertar.

  • start_row (entero opcional, predeterminado 0): Índice de fila basado en 0 donde comenzar a insertar filas. Si se omite, el valor predeterminado es 0 (inserta al principio).

  • Devuelve: Resultado de la operación (respuesta de batchUpdate).

• list_sheets: Enumera 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 con los 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 con las propiedades de la nueva hoja.

• get_multiple_sheet_data: Obtiene datos de varios 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 con los parámetros de la consulta y los data obtenidos o un error. Cada data es una respuesta de values.get.

• get_multiple_spreadsheet_summary: Obtiene títulos, nombres de hojas/pestañas, encabezados y las primeras filas de varias 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 (incluido el 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 electrónicos 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 electrónico 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 (p. ej., "Sheet1").

  • count (entero): Número de columnas vacías a insertar.

  • start_column (entero opcional, predeterminado 0): Índice de columna basado en 0 donde comenzar a insertar. Si se omite, el valor predeterminado es 0 (inserta al principio).

  • Devuelve: Resultado de la operación (respuesta de 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 (p. ej., "Sheet1").

  • 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 (p. ej., "Sheet1").

  • new_name (cadena): Nuevo nombre de la hoja/pestaña (p. ej., "Transactions").

  • Devuelve: Resultado de la operación (respuesta de 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 (p. ej., "Sheet1").

  • 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 (p. 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 obligatoria antes de ejecutar el servidor.

1. Crear/Seleccionar un proyecto de GCP: Vaya a la Consola de Google Cloud.

2. Habilitar APIs: Navegue a "API 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 la cuenta de servicio).

🔑 Autenticación y variables de entorno (Detallado)

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

Consulte la Guía de referencia de IDs para obtener 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 necesita navegador), seguro, ideal para entornos de servidor. No caduca fácilmente.

• Pasos:

  1. Crear cuenta de servicio: En la consola de GCP -> "IAM y administración" -> "Cuentas de servicio".

     • Haga clic en "+ CREAR CUENTA DE SERVICIO". Asígnele un nombre (p. ej., mcp-sheets-service).

     • Conceda roles: Agregue el rol Editor para acceso amplio, o roles más granulares (como roles/drive.file y roles específicos de Sheets) para permisos más estrictos.

     • Haga clic en "Listo". Busque 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 (p. ej., "AI Managed Sheets").

     • 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).

     • Conceda acceso de Editor. Desmarque "Notificar a las personas". Haga 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. (Consulte Inicio rápido ultrarrápido para ver ejemplos específicos por sistema operativo)

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

• ¿Por qué? Para uso personal o desarrollo local donde el inicio de sesión interactivo en el navegador es aceptable.

• Pasos:

  1. Configurar la pantalla de consentimiento de OAuth: En la consola de GCP -> "API y servicios" -> "Pantalla de consentimiento de OAuth". Seleccione "Externo", complete la información requerida, agregue ámbitos (.../auth/spreadsheets, .../auth/drive), agregue usuarios de prueba si es necesario.

  2. Crear ID de cliente OAuth: En la consola de GCP -> "API y servicios" -> "Credenciales". "+ CREAR CREDENCIALES" -> "ID de cliente de OAuth" -> Tipo: Aplicación de escritorio. Asígnele un nombre. "CREAR". Descargue el JSON.

  3. Establecer 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, se proporciona el contenido del archivo, codificado en Base64, directamente en una variable de entorno.

• Pasos:

  1. Obtén tu archivo JSON de credenciales (ya sea la clave de cuenta de servicio o el 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. Establece 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 las 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. Establece un proyecto de cuota: gcloud auth application-default set-quota-project <project_id> (reemplaza <project_id> con el ID de tu proyecto de Google Cloud)

  • Google Cloud: Adjunta una cuenta de servicio a tu recurso de cómputo

  • Variable de entorno: Establece GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json (estándar de Google)

• No se necesitan variables de entorno adicionales - ADC se utiliza 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 estableces 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 ha expirado

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 el Inicio rápido ultrarrápido, esta es la forma más sencilla. Establece 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. Establecer 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 se inicia con --transport sse y escucha en HOST/PORT. Apunta tu cliente MCP a http://localhost:8000 usando transporte SSE.

🔌 Uso con Claude Desktop

Añade 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"
      }
    }
  }
}

🍎 Nota para macOS: Si obtienes un error spawn uvx ENOENT, usa la ruta completa a uvx:

{
  "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"
      }
    }
  }
}

Reemplaza yourusername con tu nombre de usuario real.

{
  "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"
      }
    }
  }
}

Nota: Es posible que se abra un navegador para el inicio de sesión de Google en el primer uso. Asegúrate de que TOKEN_PATH sea escribible.

🍎 Nota para macOS: Si obtienes un error spawn uvx ENOENT, reemplaza "command": "uvx" con "command": "/Users/yourusername/.local/bin/uvx" (reemplaza yourusername con tu nombre de usuario real).

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

Nota: Pega la cadena Base64 completa para CREDENTIALS_CONFIG. DRIVE_FOLDER_ID sigue siendo necesario para el contexto de la carpeta de la cuenta de servicio.

🍎 Nota para macOS: Si obtienes un error spawn uvx ENOENT, reemplaza "command": "uvx" con "command": "/Users/yourusername/.local/bin/uvx" (reemplaza yourusername con tu nombre de usuario real).

Opción 1: Con GOOGLE_APPLICATION_CREDENTIALS

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

Opción 2: Con gcloud auth (sin necesidad de variables de entorno)

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

Requisitos previos:

1. Ejecuta primero 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.

2. Establece el proyecto de cuota: gcloud auth application-default set-quota-project <project_id>

🍎 Nota para macOS: Si obtienes un error spawn uvx ENOENT, reemplaza "command": "uvx" con "command": "/Users/yourusername/.local/bin/uvx" (reemplaza yourusername con tu nombre de usuario real).

{
  "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"
      }
    }
  }
}

Nota: Usa la bandera --directory para especificar la ruta del proyecto y ajusta las rutas para que coincidan con la ubicación real de tu espacio de trabajo.

💬 Ejemplos de indicaciones para Claude

Una vez conectado, prueba indicaciones como:

• "List all spreadsheets I have access to." (o "in my AI Managed Sheets folder")

• "Create a new spreadsheet titled 'Quarterly Sales Report Q3 2024'."

• "In the 'Quarterly Sales Report' spreadsheet, get the data from Sheet1 range A1 to E10."

• "Add a new sheet named 'Summary' to the spreadsheet with ID 1aBcDeFgHiJkLmNoPqRsTuVwXyZ."

• "In my 'Project Tasks' spreadsheet, Sheet 'Tasks', update cell B2 to 'In Progress'."

• "Append these rows to the 'Log' sheet in spreadsheet XYZ: [['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']]"

• "Get a summary of the spreadsheets 'Sales Data' and 'Inventory Count'."

• "Share the 'Team Vacation Schedule' spreadsheet with team@example.com as a reader and manager@example.com as a writer. Don't send notifications."

• "Create a column chart in my 'Sales Report' spreadsheet showing monthly revenue from data in range A1:B13."

• "Add a pie chart to the 'Market Analysis' sheet with data from A1:B5 titled 'Market Share by Product'."

• "In spreadsheet abc123, create a line chart on Sheet1 from range A1:C10 with title 'Growth Trends' and labels 'Month' and 'Revenue'."

🆔 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 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 en kazz187/mcp-google-spreadsheet.

• Utiliza las bibliotecas de cliente de Google API Python.