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

• Node.js 18+
• Service Account de Google Cloud con permisos de Sheets
• El spreadsheet debe estar compartido con el email del Service Account

Licencia

MIT