Google Sheets

Un servidor para la integración completa de Google Sheets, que requiere credenciales de OAuth de Google.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de Google Sheets

Un servidor de Model Context Protocol (MCP) que proporciona una integración completa con Google Sheets. Este servidor te permite crear, leer, actualizar y gestionar hojas de cálculo de Google Sheets de forma programática.

🎯 Propósito

Este servidor te permite:

  • Crear nuevas hojas de cálculo de Google Sheets con nombres de hoja personalizados
  • Leer datos de cualquier rango en una hoja de cálculo
  • Escribir datos en rangos específicos
  • Añadir nuevas filas a datos existentes
  • Limpiar rangos de datos
  • Obtener información y metadatos de la hoja de cálculo
  • Actualizar por lotes múltiples rangos de manera eficiente

🛠️ Herramientas Disponibles

Operaciones Principales

  • create-spreadsheet

    • Crea una nueva hoja de cálculo de Google Sheets
    • Entrada: title (obligatorio), sheet_names (array opcional)
    • Devuelve: ID de la hoja de cálculo, URL y nombres de hojas creadas

  • read-range

    • Lee datos de un rango específico
    • Entrada: spreadsheet_id, range_name (p. ej., 'Sheet1!A1:C10')
    • Devuelve: Array 2D de valores de celdas

  • write-range

    • Escribe datos en un rango específico (sobrescribe datos existentes)
    • Entrada: spreadsheet_id, range_name, values (array 2D)
    • Devuelve: Estadísticas de actualización

  • append-rows

    • Añade filas al final de un rango
    • Entrada: spreadsheet_id, range_name, values (array 2D)
    • Devuelve: Estadísticas de actualización

  • clear-range

    • Limpia todos los datos de un rango especificado
    • Entrada: spreadsheet_id, range_name
    • Devuelve: Confirmación del rango limpiado

  • get-spreadsheet-info

    • Obtiene metadatos sobre una hoja de cálculo
    • Entrada: spreadsheet_id
    • Devuelve: Título, URL, información de hojas, dimensiones

  • batch-update

    • Realiza múltiples actualizaciones de rangos en una sola solicitud
    • Entrada: spreadsheet_id, updates (array de pares rango/valores)
    • Devuelve: Estadísticas totales de actualización

Prompts

  • manage-sheets: Prompt general de gestión de Google Sheets para asistentes de IA

🚀 Configuración

1. Configuración de la API de Google Sheets

  1. Crea un proyecto de Google Cloud o usa uno existente
  2. Habilita la API de Google Sheets
  3. Configura una pantalla de consentimiento de OAuth
    • Selecciona "Externa" para fines de prueba
    • Añade tu correo electrónico como usuario de prueba
  4. Añade el alcance de OAuth: https://www.googleapis.com/auth/spreadsheets
  5. Crea credenciales de ID de cliente OAuth 2.0
    • Elige "Aplicación de escritorio"
  6. Descarga el archivo JSON de credenciales
  7. Guárdalo de forma segura y anota la ruta del archivo

2. Instalación

Usando uv (recomendado):

cd sheets-mcp-server
uv sync

3. Autenticación

En la primera ejecución, el servidor abrirá un navegador para la autenticación OAuth. Los tokens de acceso se guardarán en el --token-path especificado para uso futuro.

💼 Uso

Uso Independiente

uv run sheets \
  --creds-file-path /path/to/your/credentials.json \
  --token-path /path/to/your/tokens.json

Integración con Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/sheets-mcp-server",
        "run",
        "sheets",
        "--creds-file-path",
        "/path/to/your/credentials.json",
        "--token-path",
        "/path/to/your/tokens.json"
      ]
    }
  }
}

Integración con Otros Clientes MCP

Este servidor sigue el protocolo MCP estándar y puede integrarse con cualquier cliente compatible con MCP.

📋 Ejemplos de Uso

Crear una Nueva Hoja de Cálculo

{
  "tool": "create-spreadsheet",
  "arguments": {
    "title": "My Data Analysis",
    "sheet_names": ["Data", "Analysis", "Charts"]
  }
}

Leer Datos

{
  "tool": "read-range",
  "arguments": {
    "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "range_name": "Sheet1!A1:E10"
  }
}

Escribir Datos

{
  "tool": "write-range",
  "arguments": {
    "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "range_name": "Sheet1!A1:C3",
    "values": [
      ["Name", "Age", "City"],
      ["Alice", "30", "New York"],
      ["Bob", "25", "San Francisco"]
    ]
  }
}

Añadir Nuevos Datos

{
  "tool": "append-rows",
  "arguments": {
    "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "range_name": "Sheet1!A:C",
    "values": [
      ["Charlie", "35", "Chicago"],
      ["Diana", "28", "Boston"]
    ]
  }
}

Actualizaciones por Lotes

{
  "tool": "batch-update",
  "arguments": {
    "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "updates": [
      {
        "range": "Sheet1!A1:B2",
        "values": [["Header1", "Header2"], ["Data1", "Data2"]]
      },
      {
        "range": "Sheet1!D1:E2",
        "values": [["Header3", "Header4"], ["Data3", "Data4"]]
      }
    ]
  }
}

🧪 Pruebas

Con MCP Inspector

Prueba el servidor usando MCP Inspector:

npx @modelcontextprotocol/inspector uv run sheets \
  --creds-file-path /path/to/credentials.json \
  --token-path /path/to/tokens.json

Pruebas Manuales

  1. Crea una hoja de cálculo de prueba
  2. Lee algunos datos para verificar la conectividad
  3. Escribe datos de prueba para asegurarte de que los permisos de escritura funcionan
  4. Prueba diferentes formatos de rango (notación A1, rangos con nombre, etc.)

📊 Casos de Uso Comunes

Flujos de Trabajo de Análisis de Datos

1. Create spreadsheet for analysis
2. Import raw data via append-rows
3. Read data for processing
4. Write calculated results back
5. Generate reports and summaries

Gestión de Contenidos

1. Create content tracking spreadsheet
2. Append new content entries
3. Update status and metadata
4. Generate content reports

Gestión de Proyectos

1. Create project tracking sheet
2. Add tasks and milestones
3. Update progress and status
4. Generate project dashboards

Sincronización de Datos

1. Read data from external systems
2. Transform and validate data
3. Write to Google Sheets for sharing
4. Keep data synchronized across platforms

🔧 Funciones Avanzadas

Formatos de Rango Soportados

  • Notación A1: Sheet1!A1:C10
  • Rangos con nombre: MyNamedRange
  • Columnas completas: Sheet1!A:C
  • Filas completas: Sheet1!1:5
  • Rangos abiertos: Sheet1!A1:C

Manejo de Errores

El servidor incluye un manejo integral de errores para:

  • Fallos de autenticación y renovación de tokens
  • Tiempos de espera de red y problemas de conectividad
  • IDs de hojas de cálculo o nombres de rangos no válidos
  • Errores de permisos
  • Límites de cuota de API
  • Entradas de datos malformadas

Consideraciones de Rendimiento

  • Usa asyncio.to_thread para llamadas API no bloqueantes
  • Soporta operaciones por lotes para mayor eficiencia
  • Maneja los límites de velocidad de la API de Google Sheets con elegancia
  • Optimizado para operaciones de datos tanto pequeñas como grandes

🔒 Seguridad y Permisos

Alcances de OAuth Requeridos

  • https://www.googleapis.com/auth/spreadsheets - Acceso completo a Google Sheets

Mejores Prácticas de Seguridad

  • Almacena las credenciales de forma segura
  • Usa variables de entorno para rutas sensibles
  • Implementa controles de acceso adecuados
  • Rota los tokens de acceso regularmente
  • Supervisa el uso de API y las cuotas

🤝 Contribución y Extensión

Este servidor está diseñado para ser fácilmente extensible. Mejoras comunes:

Funciones Adicionales

  • Operaciones de formato (negrita, colores, bordes)
  • Soporte de fórmulas para celdas calculadas
  • Creación y gestión de gráficos
  • Reglas de formato condicional
  • Restricciones de validación de datos
  • Tablas dinámicas y resúmenes

Mejoras de Integración

  • Conectores de bases de datos para importación/exportación de datos
  • Importación/exportación de archivos CSV/Excel
  • Funciones de colaboración en tiempo real
  • Notificaciones webhook para cambios
  • Búsqueda avanzada y filtrado

Optimizaciones de Rendimiento

  • Estrategias de caché para datos de acceso frecuente
  • Soporte de streaming para conjuntos de datos grandes
  • Procesamiento paralelo para operaciones masivas
  • Agrupación de conexiones para escenarios de alto rendimiento

📚 Referencia de API

Límites de la API de Google Sheets

  • 100 solicitudes por 100 segundos por usuario
  • 1000 solicitudes por 100 segundos (cuota total)
  • Máximo 10 millones de celdas por hoja de cálculo
  • Máximo 200 hojas por hoja de cálculo

Formatos de Respuesta

Todas las herramientas devuelven respuestas estructuradas con:

  • Indicadores de estado (éxito/error)
  • Mensajes de error detallados cuando corresponde
  • Estadísticas de actualización para operaciones de escritura
  • Datos estructurados para operaciones de lectura

🆘 Solución de Problemas

Problemas Comunes

  1. Errores de Autenticación

    • Verifica la ruta del archivo de credenciales
    • Comprueba la configuración de la pantalla de consentimiento de OAuth
    • Asegúrate de que los alcances correctos estén configurados

  2. Errores de Permisos

    • Verifica los permisos de uso compartido de la hoja de cálculo
    • Comprueba si la hoja de cálculo existe
    • Asegúrate de que la cuenta tenga acceso de edición

  3. Errores de Rango

    • Valida el formato de notación A1
    • Comprueba los nombres de las hojas por errores tipográficos
    • Verifica los límites del rango

  4. Cuota Excedida

    • Implementa limitación de solicitudes
    • Usa operaciones por lotes cuando sea posible
    • Supervisa el uso en Google Cloud Console

¡Listo para potenciar tus flujos de trabajo de Google Sheets con operaciones automatizadas! 🚀