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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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