# 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
```bash
cd mcp-spreadsheets
npm install
npm run build
```
### 2. Configurar credenciales
Copia tu archivo de credenciales de Google Service Account a la carpeta:
```bash
cp /ruta/a/tu/service-account.json ./credentials.json
```
O configura variables de entorno:
```bash
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`):
```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
