MCP Spreadsheets
Servidor MCP (Model Context Protocol) para control total de Google Sheets desde Claude Code.
Descripción
Este MCP permite manipular spreadsheets de Google directamente desde Claude Code sin necesidad de escribir scripts. Cada operación se ejecuta en segundos mediante comandos directos.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Claude Code │────▶│ MCP Server │────▶│ Google Sheets │
│ (tu prompt) │ │ (siempre on) │ │ API v4 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Instalación
1. Instalar dependencias
cd mcp-spreadsheets
npm install
npm run build
2. Configurar credenciales
Copia tu archivo de credenciales de Google Service Account a la carpeta:
cp /ruta/a/tu/service-account.json ./credentials.json
O configura variables de entorno:
export GOOGLE_SERVICE_ACCOUNT_PATH=/ruta/a/credentials.json
3. Registrar en Claude Code
Agrega a tu archivo de configuración de Claude Code (~/.claude.json o settings.json):
{
"mcpServers": {
"spreadsheets": {
"command": "node",
"args": ["/ruta/completa/a/mcp-spreadsheets/dist/index.js"],
"env": {
"GOOGLE_SERVICE_ACCOUNT_PATH": "/ruta/a/credentials.json"
}
}
}
}
Categorías y Tools
Datos
Operaciones de lectura y escritura de datos.
Tool | Descripción | Parámetros |
sheets_read_range
| Lee datos de un rango | spreadsheetId, sheetName, range
|
sheets_write_range
| Escribe datos en un rango | spreadsheetId, sheetName, range, values
|
sheets_append_rows
| Agrega filas al final | spreadsheetId, sheetName, rows
|
sheets_delete_rows
| Elimina filas | spreadsheetId, sheetName, startIndex, count
|
sheets_get_rows
| Obtiene filas como objetos | spreadsheetId, sheetName, limit?
|
Ejemplos:
// Leer datos
sheets_read_range(spreadsheetId: "abc123", sheetName: "Ventas", range: "A1:D10")
// Escribir datos
sheets_write_range(spreadsheetId: "abc123", sheetName: "Ventas", range: "A1", values: [["Nombre", "Precio"], ["Producto 1", 100]])
// Agregar filas
sheets_append_rows(spreadsheetId: "abc123", sheetName: "Ventas", rows: [{Nombre: "Producto 2", Precio: 200}])
Formato
Aplicar estilos visuales a celdas.
Tool | Descripción | Parámetros |
sheets_format_range
| Aplica formato a celdas | spreadsheetId, sheetName, range, backgroundColor?, textColor?, bold?, italic?, fontSize?, horizontalAlignment?
|
sheets_clear_format
| Limpia todo el formato | spreadsheetId, sheetName, range
|
Ejemplos:
// Poner fondo verde y texto blanco en negrita
sheets_format_range(
spreadsheetId: "abc123",
sheetName: "Ventas",
range: "A1:D1",
backgroundColor: "#00ff00",
textColor: "#ffffff",
bold: true
)
// Limpiar formato
sheets_clear_format(spreadsheetId: "abc123", sheetName: "Ventas", range: "A2:D100")
Formato Condicional
Reglas automáticas que cambian el formato según condiciones.
Tool | Descripción | Parámetros |
sheets_get_conditional_rules
| Lista todas las reglas | spreadsheetId, sheetName
|
sheets_add_conditional_rule
| Agrega una regla | spreadsheetId, sheetName, formula, backgroundColor?, textColor?, bold?, priority?
|
sheets_delete_conditional_rule
| Elimina una regla por índice | spreadsheetId, sheetName, index
|
sheets_clear_conditional_rules
| Elimina TODAS las reglas | spreadsheetId, sheetName
|
Ejemplos:
// Ver reglas existentes
sheets_get_conditional_rules(spreadsheetId: "abc123", sheetName: "Reservas")
// Agregar regla: si Canal = "airbnb", fondo verde
sheets_add_conditional_rule(
spreadsheetId: "abc123",
sheetName: "Reservas",
formula: '=LOWER($J2)="airbnb"',
backgroundColor: "#ccffcc",
priority: 0
)
// Agregar regla: si Total = 0, fondo amarillo
sheets_add_conditional_rule(
spreadsheetId: "abc123",
sheetName: "Reservas",
formula: '=AND(LEN($A2)>0,$V2=0)',
backgroundColor: "#ffffcc",
priority: 1
)
// Eliminar regla índice 0
sheets_delete_conditional_rule(spreadsheetId: "abc123", sheetName: "Reservas", index: 0)
// Limpiar todas las reglas
sheets_clear_conditional_rules(spreadsheetId: "abc123", sheetName: "Reservas")
Hojas
Gestión de hojas dentro del spreadsheet.
Tool | Descripción | Parámetros |
sheets_list_sheets
| Lista todas las hojas | spreadsheetId
|
sheets_create_sheet
| Crea nueva hoja | spreadsheetId, title, headers?
|
sheets_delete_sheet
| Elimina una hoja | spreadsheetId, sheetName
|
sheets_rename_sheet
| Renombra una hoja | spreadsheetId, oldName, newName
|
sheets_duplicate_sheet
| Duplica una hoja | spreadsheetId, sheetName, newName
|
sheets_hide_sheet
| Oculta/muestra hoja | spreadsheetId, sheetName, hidden
|
Ejemplos:
// Ver todas las hojas
sheets_list_sheets(spreadsheetId: "abc123")
// Crear hoja con headers
sheets_create_sheet(
spreadsheetId: "abc123",
title: "Reporte Mensual",
headers: ["Fecha", "Ventas", "Gastos", "Ganancia"]
)
// Duplicar hoja
sheets_duplicate_sheet(spreadsheetId: "abc123", sheetName: "Plantilla", newName: "Enero 2024")
// Ocultar hoja
sheets_hide_sheet(spreadsheetId: "abc123", sheetName: "Datos Internos", hidden: true)
Celdas
Operaciones sobre celdas individuales o rangos.
Tool | Descripción | Parámetros |
sheets_merge_cells
| Combina celdas | spreadsheetId, sheetName, range
|
sheets_unmerge_cells
| Separa celdas combinadas | spreadsheetId, sheetName, range
|
sheets_freeze_rows
| Congela filas superiores | spreadsheetId, sheetName, count
|
sheets_freeze_columns
| Congela columnas izquierdas | spreadsheetId, sheetName, count
|
sheets_set_column_width
| Ajusta ancho de columna | spreadsheetId, sheetName, column, width
|
sheets_set_row_height
| Ajusta altura de fila | spreadsheetId, sheetName, row, height
|
Ejemplos:
// Combinar celdas para título
sheets_merge_cells(spreadsheetId: "abc123", sheetName: "Reporte", range: "A1:D1")
// Congelar primera fila (headers)
sheets_freeze_rows(spreadsheetId: "abc123", sheetName: "Datos", count: 1)
// Ajustar ancho de columna A a 200px
sheets_set_column_width(spreadsheetId: "abc123", sheetName: "Datos", column: "A", width: 200)
Validación
Restricciones y listas desplegables.
Tool | Descripción | Parámetros |
sheets_add_dropdown
| Agrega lista desplegable | spreadsheetId, sheetName, range, options
|
sheets_remove_validation
| Elimina validación | spreadsheetId, sheetName, range
|
Ejemplos:
// Agregar dropdown de estados
sheets_add_dropdown(
spreadsheetId: "abc123",
sheetName: "Tareas",
range: "C2:C100",
options: ["Pendiente", "En Progreso", "Completado", "Cancelado"]
)
// Quitar validación
sheets_remove_validation(spreadsheetId: "abc123", sheetName: "Tareas", range: "C2:C100")
Filtros
Activar y desactivar filtros automáticos.
Tool | Descripción | Parámetros |
sheets_set_filter
| Activa filtro en rango | spreadsheetId, sheetName, range
|
sheets_clear_filter
| Elimina filtro | spreadsheetId, sheetName
|
Ejemplos:
// Activar filtro en tabla
sheets_set_filter(spreadsheetId: "abc123", sheetName: "Ventas", range: "A1:F100")
// Quitar filtro
sheets_clear_filter(spreadsheetId: "abc123", sheetName: "Ventas")
Protección
Proteger rangos contra edición accidental.
Tool | Descripción | Parámetros |
sheets_protect_range
| Protege un rango | spreadsheetId, sheetName, range, description
|
Ejemplos:
// Proteger fórmulas
sheets_protect_range(
spreadsheetId: "abc123",
sheetName: "Calculadora",
range: "E1:E100",
description: "Columna de fórmulas - No editar"
)
Info
Información general del spreadsheet.
Tool | Descripción | Parámetros |
sheets_get_info
| Info del spreadsheet | spreadsheetId
|
Ejemplos:
// Ver información
sheets_get_info(spreadsheetId: "abc123")
// Retorna: { title, locale, timeZone, sheets: [...] }
Base de Datos (Reservas)
Consultas directas a PostgreSQL para obtener información de reservas.
Tool | Descripción | Parámetros |
db_get_reservas_futuras
| Reservas futuras de Pa'Cartagena | - |
db_get_tours_terceros
| Reservas de Tours y Terceros | - |
db_get_reserva_by_id
| Buscar reserva por ID | bookingId
|
db_count_reservas
| Contar reservas (total, futuras, tours) | - |
db_get_reservas_por_fecha
| Reservas entre dos fechas | desde, hasta
|
db_get_reservas_por_canal
| Reservas de un canal | canal
|
db_get_estadisticas_canales
| Estadísticas por canal | - |
Ejemplos:
// ¿Hay tours esta semana?
db_get_tours_terceros()
// ¿Cuántas reservas de Airbnb hay?
db_get_reservas_por_canal(canal: "airbnb")
// Estadísticas generales
db_count_reservas()
// Retorna: { total: 2536, futuras: 107, tours: 1 }
// Reservas de febrero
db_get_reservas_por_fecha(desde: "2026-02-01", hasta: "2026-02-28")
Nota: Requiere configurar DATABASE_URL en el entorno.
Resumen de Categorías
Categoría | Tools | Descripción |
Datos | 5 | Leer, escribir, insertar, eliminar filas |
Formato | 2 | Colores, fuentes, negrita, alineación |
Formato Condicional | 4 | Reglas automáticas por fórmula |
Hojas | 6 | Crear, eliminar, renombrar, duplicar, ocultar |
Celdas | 6 | Merge, freeze, ancho/alto |
Validación | 2 | Dropdowns, restricciones |
Filtros | 2 | Activar/desactivar filtros |
Protección | 1 | Proteger rangos |
Info | 1 | Información del spreadsheet |
Base de Datos | 7 | Consultar reservas de PostgreSQL |
TOTAL | 36 tools | |
Flujo de Uso
Antes (con scripts)
Usuario pide cambio
→ Desarrollador edita código
→ Compila
→ Ejecuta
→ Verifica resultado
≈ 2-5 minutos
Ahora (con MCP)
Usuario pide cambio
→ Claude invoca tool
→ Resultado inmediato
≈ 2-5 segundos
Notas Técnicas
Autenticación: Service Account de Google (no requiere OAuth interactivo)
API: Google Sheets API v4
Protocolo: Model Context Protocol (MCP) sobre stdio
Caché: Los documentos se cachean para evitar re-cargas innecesarias
Requisitos
Licencia
MIT
