Google Sheets

Servidor MCP de Google Sheets

Un servidor de Protocolo de Contexto de Modelo (MCP) para la integración con la API de Google Sheets. Permite leer, escribir y gestionar documentos de Google Sheets directamente desde tu cliente MCP (por ejemplo, Claude Code, Claude Desktop, Cursor, etc.).

Características principales

• Integración completa con Google Sheets: Lee, escribe y gestiona hojas de cálculo
• Operaciones avanzadas: Operaciones por lotes, formato, gráficos y formato condicional
• Autenticación flexible: Compatibilidad con credenciales basadas en archivos y en cadenas JSON
• Listo para producción: Construido con TypeScript, manejo integral de errores y cobertura completa de pruebas

Requisitos

• Node.js v20 o superior
• Proyecto de Google Cloud con la API de Sheets habilitada
• Cuenta de servicio con archivo de clave JSON
• npm

Primeros pasos

Instalación rápida (recomendada)

Añade la siguiente configuración a tu cliente MCP:

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

[!NOTE] Usar mcp-gsheets@latest garantiza que tu cliente MCP siempre utilice la versión más reciente del servidor MCP de Google Sheets.

Configuración del cliente MCP

claude mcp add mcp-gsheets npx mcp-gsheets@latest

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

Configuración de Google Cloud

1. Ve a Consola de Google Cloud
2. Crea un nuevo proyecto o selecciona uno existente
3. Habilita la API de Google Sheets:
   • Navega a "APIs y servicios" → "Biblioteca"
   • Busca "Google Sheets API" y haz clic en "Habilitar"
4. Crea la cuenta de servicio:
   • Ve a "APIs y servicios" → "Credenciales"
   • Haz clic en "Crear credenciales" → "Cuenta de servicio"
   • En la lista de cuentas de servicio, haz clic en los tres puntos de la columna Actions → Manage keys → Add key → Create new key → selecciona formato JSON
   • Descarga el archivo de clave JSON
5. Comparte tus hojas de cálculo:
   • Abre tu hoja de Google
   • Haz clic en Compartir y añade el correo de la cuenta de servicio (del archivo JSON)
   • Otorga permisos de "Editor"

Métodos de autenticación alternativos

Opción 1: Autenticación con cadena JSON

En lugar de usar una ruta de archivo para las credenciales, puedes proporcionar las credenciales de la cuenta de servicio directamente como una cadena JSON. Esto es útil para entornos contenedorizados, canalizaciones de CI/CD o cuando quieres evitar gestionar archivos de credenciales.

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\",\"project_id\":\"your-project\",\"private_key_id\":\"...\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"...@....iam.gserviceaccount.com\",\"client_id\":\"...\",\"auth_uri\":\"https://accounts.google.com/o/oauth2/auth\",\"token_uri\":\"https://oauth2.googleapis.com/token\",\"auth_provider_x509_cert_url\":\"https://www.googleapis.com/oauth2/v1/certs\",\"client_x509_cert_url\":\"...\"}"
      }
    }
  }
}

Nota: Al usar GOOGLE_SERVICE_ACCOUNT_KEY:

• Todo el JSON debe estar en una sola línea
• Todas las comillas deben escaparse con barras invertidas
• Los saltos de línea en la clave privada deben representarse como \\n
• Si el JSON incluye un project_id, puedes omitir GOOGLE_PROJECT_ID

Opción 2: Autenticación con clave privada (simplificada)

Para el enfoque más fácil de usar, puedes proporcionar solo la clave privada y el correo directamente. Este es el método más simple y solo requiere dos campos de tu JSON de cuenta de servicio:

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCgR6bvMNOUHZ29\\n+YgbVHAXsT/s+L/jnXTCB193zikCzspSBSfxLu8VRDjkNq9WUoDxizTATzMFNvNf\\n...\\n-----END PRIVATE KEY-----\\n",
        "GOOGLE_CLIENT_EMAIL": "spreadsheet@your-project.iam.gserviceaccount.com"
      }
    }
  }
}

Nota: Al usar GOOGLE_PRIVATE_KEY:

• Los saltos de línea en la clave privada deben representarse como \\n
• La clave privada debe incluir los marcadores -----BEGIN PRIVATE KEY----- y -----END PRIVATE KEY-----
• El correo del cliente debe ser el correo de la cuenta de servicio de tu archivo JSON
• GOOGLE_PROJECT_ID es opcional al usar este método

Configuración de desarrollo local

Si quieres desarrollar o contribuir a este proyecto, puedes clonarlo y compilarlo localmente:

# Clone the repository
git clone https://github.com/freema/mcp-gsheets.git
cd mcp-gsheets

# Install dependencies
npm install

# Build the project
npm run build

Script de configuración interactivo

Ejecuta el script de configuración interactivo para configurar tu cliente MCP local:

npm run setup

Esto:

• Te guiará a través de la configuración
• Detectarás automáticamente tu instalación de Node.js (incluido nvm)
• Encontrará tu configuración de Claude Desktop
• Creará la configuración JSON adecuada
• Opcionalmente creará un archivo .env para desarrollo

Configuración local manual

Si prefieres la configuración manual con una compilación local, añade a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-gsheets/dist/index.js"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

📦 Compilación y desarrollo

Comandos de desarrollo

# Development mode with hot reload
npm run dev

# Build for production
npm run build

# Type checking
npm run typecheck

# Clean build artifacts
npm run clean

# Run MCP inspector for debugging
npm run inspector

# Run MCP inspector in development mode
npm run inspector:dev

Ejecutor de tareas (alternativa)

Si tienes Task instalado:

# Install dependencies
task install

# Build the project
task build

# Run in development mode
task dev

# Run linter
task lint

# Format code
task fmt

# Run all checks
task check

Configuración de desarrollo

1. Crea el archivo .env para pruebas:

cp .env.example .env
# Edit .env with your credentials:
# GOOGLE_PROJECT_ID=your-project-id
# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
# TEST_SPREADSHEET_ID=your-test-spreadsheet-id

2. Ejecuta en modo de desarrollo:

npm run dev  # Watch mode with auto-reload

🎚️ Reducción del costo de contexto con conjuntos de herramientas

Las 44 herramientas juntas cuestan aproximadamente 9,900 tokens de contexto en cada sesión, antes de que el modelo haga cualquier cosa. La mayoría de los flujos de trabajo necesitan una fracción de eso. GSHEETS_TOOLSETS limita qué herramientas expone el servidor:

{
  "mcpServers": {
    "gsheets": {
      "command": "npx",
      "args": ["mcp-gsheets"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/key.json",
        "GSHEETS_TOOLSETS": "core,charts"
      }
    }
  }
}

Costo medido de tools/list:

Notas:

• El valor predeterminado no cambia — deja GSHEETS_TOOLSETS sin definir y obtienes todas las herramientas, exactamente como antes.
• core siempre está incluido. GSHEETS_TOOLSETS=charts significa "gráficos además del núcleo", no "solo gráficos" — sin el núcleo el servidor no puede leer una celda.
• Un error tipográfico es un error de inicio, no una lista de herramientas silenciosamente más pequeña.
• GSHEETS_READ_ONLY=true elimina todas las herramientas de escritura y puede combinarse con GSHEETS_TOOLSETS. Se aplica cuando se llama a una herramienta, no solo cuando se construye la lista, por lo que un cliente no puede escribir nombrando una herramienta oculta.

Todas las herramientas también llevan anotaciones MCP (readOnlyHint, destructiveHint, idempotentHint), para que los clientes puedan omitir las confirmaciones en las lecturas y advertir antes de operaciones destructivas.

📋 Herramientas disponibles

Lectura de datos

Escritura de datos

Gestión de hojas

Formato de celdas

Tablas nativas

Gráficos

Herramientas de Lectura / Instantánea

🔧 Calidad del Código

Linting

# Run ESLint
npm run lint

# Fix auto-fixable issues
npm run lint:fix

Formato

# Check formatting with Prettier
npm run format:check

# Format code
npm run format

Comprobación de Tipos

# Run TypeScript type checking
npm run typecheck

❗ Solución de Problemas

Problemas Comunes

"Error de autenticación"

• Si usas autenticación basada en archivos: verifica que la ruta de la clave JSON sea absoluta y correcta
• Si usas autenticación con cadena JSON: asegúrate de que el JSON esté correctamente escapado y sea válido
• Si usas autenticación con clave privada: comprueba que la clave privada incluya los marcadores BEGIN/END y que los saltos de línea estén escapados como \\n
• Verifica que GOOGLE_CLIENT_EMAIL sea un correo electrónico válido de cuenta de servicio
• Comprueba que GOOGLE_PROJECT_ID coincida con tu proyecto (o esté incluido en el JSON para la autenticación JSON completa)
• Asegúrate de que la API de Sheets esté habilitada

"Permiso denegado"

• Comparte la hoja de cálculo con el correo de la cuenta de servicio
• La cuenta de servicio necesita el rol de "Editor"
• Comprueba el correo en el archivo JSON (campo client_email)

"Hoja de cálculo no encontrada"

• Verifica el ID de la hoja de cálculo desde la URL
• Formato: https://docs.google.com/spreadsheets/d/[SPREADSHEET_ID]/edit

Problemas de conexión MCP

• Asegúrate de usar la versión compilada (dist/index.js)
• Comprueba que la ruta de Node.js sea correcta en la configuración de Claude Desktop
• Busca errores en los registros de Claude Desktop
• Usa npm run inspector para depurar

🔍 Cómo Encontrar IDs

ID de la hoja de cálculo

Desde la URL:

https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit
                                        ↑ This is the spreadsheet ID

ID de la hoja

Usa sheets_get_metadata para listar todas las hojas con sus IDs.

📝 Consejos

1. Prueba siempre con una copia de tus datos
2. Usa operaciones por lotes para un mejor rendimiento
3. Establece permisos adecuados (solo lectura frente a edición)
4. Comprueba los límites de velocidad para operaciones grandes
5. Usa sheets_check_access para verificar los permisos antes de las operaciones

📘 Detalles de las Herramientas

sheets_get_sheet_structure

Devuelve metadatos estructurales/dimensionales ligeros de una hoja sin datos por celda. Mucho más rápido y económico que sheets_get_full_sheet_snapshot cuando solo necesitas información de diseño.

Parámetros:

• spreadsheetId (obligatorio): El ID de la hoja de cálculo
• sheetName (obligatorio): Nombre de la hoja (pestaña)

Devuelve: sheetName, sheetId, sheetIndex, tabColor, tabColorStyle, dimensions (rowCount, columnCount), frozen (rowCount, columnCount), columnWidths (matriz de tamaños en píxeles), rowHeights (matriz de tamaños en píxeles), hiddenColumns (índices basados en cero), hiddenRows (índices basados en cero), mergeCount, merges (matriz en notación A1)

sheets_get_formatting_compact

Lee el formato de celdas de un rango y lo devuelve como pares compactos A1Range → formato. Las celdas adyacentes con formato idéntico se agrupan en rangos rectangulares (codificación por longitud de ejecución), lo que reduce la salida en más del 90 % en comparación con los datos por celda.

Parámetros:

• spreadsheetId (obligatorio): El ID de la hoja de cálculo
• sheetName (obligatorio): Nombre de la hoja (pestaña)
• range (obligatorio): Rango sin prefijo de hoja, p. ej. "A1:Z85"
• useEffectiveFormat (opcional): false (predeterminado) = userEnteredFormat (solo anulaciones explícitas, salida más pequeña); true = effectiveFormat (todos los valores predeterminados heredados)
• fields (opcional): Matriz de nombres de campos de formato a incluir, p. ej. ["backgroundColor", "textFormat", "borders"]

Devuelve: { range, formatType, rangeCount, data: { "A1:C3": { backgroundColor: {...} }, ... } }

Campos admitidos: backgroundColor, backgroundColorStyle, textFormat, horizontalAlignment, verticalAlignment, wrapStrategy, textRotation, numberFormat, padding, borders

sheets_get_full_sheet_snapshot

Herramienta maestra de una sola llamada que devuelve todos los metadatos estructurales y de formato en una única llamada API.

Parámetros:

• spreadsheetId (obligatorio): El ID de la hoja de cálculo
• sheetName (obligatorio): Nombre de la hoja (pestaña)
• includeFormattingRange (opcional): Si se proporciona (p. ej. "A1:Z100"), el formato por celda se incluye en la respuesta
• useEffectiveFormat (opcional): Usa effectiveFormat en lugar de userEnteredFormat al incluir el formato de celdas (predeterminado: false)
• fields (opcional): Matriz de nombres de campos de formato a devolver, p. ej. ["backgroundColor", "textFormat"] — reduce el tamaño de transferencia de la API y el tamaño de la respuesta
• compactMode (opcional): Cuando true, las celdas adyacentes idénticas se agrupan en rangos rectangulares (RLE). Reduce una hoja típica de 85×28 de ~60 000 líneas a ~500 líneas (predeterminado: false)

sheets_insert_rows

Inserta nuevas filas en una posición específica de una hoja de cálculo con datos opcionales.

Parámetros:

• spreadsheetId (obligatorio): El ID de la hoja de cálculo
• range (obligatorio): Punto de anclaje en notación A1 donde se insertarán las filas (p. ej., "Sheet1!A5")
• rows (opcional): Número de filas a insertar (predeterminado: 1)
• position (opcional): 'BEFORE' o 'AFTER' la fila de anclaje (predeterminado: 'BEFORE')
• inheritFromBefore (opcional): Si se debe heredar el formato de la fila anterior (predeterminado: false)
• values (opcional): Matriz 2D de valores para rellenar las filas recién insertadas
• valueInputOption (opcional): 'RAW' o 'USER_ENTERED' (predeterminado: 'USER_ENTERED')

Ejemplos:

// Insert 1 empty row before row 5
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!A5"
}

// Insert 3 rows after row 10 with data
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!A10",
  "rows": 3,
  "position": "AFTER",
  "values": [
    ["John", "Doe", "john@example.com"],
    ["Jane", "Smith", "jane@example.com"],
    ["Bob", "Johnson", "bob@example.com"]
  ]
}

sheets_delete_columns

Elimina una o más columnas de una hoja usando un rango A1 de columna completa.

Parámetros:

• spreadsheetId (obligatorio): El ID de la hoja de cálculo
• range (obligatorio): Rango A1 de columna completa a eliminar (p. ej., "Sheet1!B:D" o "Sheet1!C:C")

Ejemplos:

// Delete columns B through D from Sheet1
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!B:D"
}

// Delete a single column from the first sheet
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "C:C"
}

sheets_delete_rows

Elimina una o más filas de una hoja usando un rango A1 de fila completa.

Parámetros:

• spreadsheetId (obligatorio): El ID de la hoja de cálculo
• range (obligatorio): Rango A1 de fila completa a eliminar (p. ej., "Sheet1!2:4" o "Sheet1!3:3")

Ejemplos:

// Delete rows 2 through 4 from Sheet1
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!2:4"
}

// Delete a single row from the first sheet
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "3:3"
}

📋 Registro de Cambios

Consulta CHANGELOG.md para ver una lista de cambios en cada versión.

🤝 Contribuciones

1. Haz un fork del repositorio
2. Crea tu rama de funcionalidad (git checkout -b feature/amazing-feature)
3. Ejecuta las pruebas y el linting (npm run check)
4. Haz commit de tus cambios (git commit -m 'Add some amazing feature')
5. Haz push a la rama (git push origin feature/amazing-feature)
6. Abre un Pull Request

👤 Autor

Tomáš Grásl - tomasgrasl.cz

📄 Licencia

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