Google Spreadsheet MCP

Integración completa de Google Sheets: leer, escribir, formatear celdas, crear gráficos, usar fórmulas y gestionar hojas de cálculo.

GitHub

Documentación

Google Sheets MCP Server

Un servidor de Model Context Protocol (MCP) que proporciona funcionalidad completa de Google Sheets. Lee, escribe, da formato a celdas, crea gráficos, usa fórmulas y gestiona hojas de cálculo directamente desde Claude, Cursor o cualquier cliente compatible con MCP.

Por qué lo construí

Creé este servidor MCP para mis tareas universitarias, donde trabajo frecuentemente con datos en Google Sheets — principalmente hojas financieras. Tareas como crear gráficos, escribir fórmulas, dar formato a tablas y organizar datos eran repetitivas y consumían tiempo. Con esta herramienta, puedo automatizar todo eso y centrarme en lo que realmente importa — el pensamiento lógico y el análisis — en lugar de hacer el mismo trabajo manual una y otra vez. :)

Características

Categoría	Capacidades
Operaciones de celdas	Leer, escribir, operaciones por lotes, añadir filas, limpiar celdas
Fórmulas	Soporte completo (`=SUM()`, `=VLOOKUP()`, `=IF()`, etc.)
Gestión de hojas	Crear, eliminar, renombrar, duplicar hojas
Formato	Negrita, cursiva, colores, alineación, anchos de columna, fusionar celdas
Gráficos	Gráficos de barras, líneas, circular, columnas, área y dispersión
Operaciones de datos	Ordenar, buscar/reemplazar, obtener la última fila
Compartir	Compartir con usuarios o hacer público

Inicio rápido

1. Instalar

cd /path/to/spreadsheet-mcp
uv sync

2. Configuración de Google Cloud (Gratis, una sola vez)

Crear proyecto: Ir a Google Cloud Console → Nuevo proyecto
Habilitar APIs:
- Habilitar API de Sheets
- Habilitar API de Drive
Crear cuenta de servicio:
- Ir a APIs y Servicios → Credenciales → Crear credenciales → Cuenta de servicio
- Descargar clave JSON → Guardar como credentials/service-account.json
Compartir hojas de cálculo: Comparte tus hojas con el correo electrónico de la cuenta de servicio (que se encuentra en el JSON)

3. Ejecutar

uv run spreadsheet-mcp

Configuración del cliente MCP

Claude Desktop

Agrega a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Claude Code (CLI)

Agrega al archivo .mcp.json de tu proyecto:

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Cursor

Agrega a la configuración de MCP de Cursor (Ajustes → MCP → Agregar servidor):

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

O agrega a ~/.cursor/mcp.json:

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Gemini CLI

Para Gemini CLI con soporte de MCP, agrega a tu configuración de MCP:

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Usando con npx (Alternativa)

Si prefieres npx en lugar de uv:

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": [
        "-y",
        "uv",
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Nota: Reemplaza /path/to/spreadsheet-mcp con la ruta real donde clonaste este repositorio.

Herramientas disponibles (27 en total)

Gestión de hojas de cálculo y hojas

Herramienta	Descripción	Ejemplo
`get_spreadsheet_info`	Obtener metadatos y lista de hojas	"Muéstrame información sobre la hoja abc123"
`create_spreadsheet`	Crear nueva hoja de cálculo	"Crea una hoja llamada 'Presupuesto 2024'"
`list_sheets`	Listar todas las hojas/pestañas	"¿Qué hojas hay en esta hoja de cálculo?"
`create_sheet`	Agregar una nueva hoja	"Agrega una hoja llamada 'Resumen'"
`delete_sheet`	Eliminar una hoja	"Elimina la hoja con ID 12345"
`rename_sheet`	Renombrar una hoja	"Renombra la hoja 0 a 'Datos'"
`duplicate_sheet`	Copiar una hoja	"Duplica la hoja principal"

Operaciones de celdas

Herramienta	Descripción	Ejemplo
`read_cells`	Leer valores de un rango	"Lee las celdas A1 a D10 de la Hoja1"
`write_cells`	Escribir valores (soporta fórmulas)	"Escribe encabezados Nombre, Edad, Puntaje en A1"
`batch_read`	Leer múltiples rangos a la vez	"Lee A1:A10 y C1:C10"
`batch_write`	Escribir en múltiples rangos	"Escribe datos en varias ubicaciones"
`append_rows`	Agregar filas al final de los datos	"Agrega estos nuevos registros"
`clear_cells`	Limpiar un rango	"Limpia las celdas B2:D10"
`get_last_row`	Encontrar la última fila con datos	"¿Cuál es la última fila en la columna A?"

Operaciones de filas/columnas

Herramienta	Descripción	Ejemplo
`insert_rows`	Insertar filas vacías	"Inserta 5 filas en la fila 10"
`insert_columns`	Insertar columnas vacías	"Inserta 2 columnas en la columna C"
`delete_rows`	Eliminar filas	"Elimina las filas 5-10"
`delete_columns`	Eliminar columnas	"Elimina la columna B"

Formato

Herramienta	Descripción	Ejemplo
`format_cells`	Aplicar formato	"Haz que la fila de encabezado esté en negrita con fondo azul"
`set_column_width`	Ajustar ancho de columna	"Establece el ancho de la columna A a 200 píxeles"
`merge_cells`	Fusionar rango de celdas	"Fusiona las celdas A1:C1 para el título"

Gráficos

Herramienta	Descripción	Ejemplo
`create_chart`	Crear gráfico incrustado	"Crea un gráfico de barras a partir de los datos de ventas"
`list_charts`	Listar todos los gráficos	"¿Qué gráficos existen en esta hoja de cálculo?"
`delete_chart`	Eliminar un gráfico	"Elimina el gráfico 123456"

Operaciones de datos

Herramienta	Descripción	Ejemplo
`sort_range`	Ordenar datos por columna	"Ordena los datos por la columna B ascendente"
`find_replace`	Buscar y reemplazar texto	"Reemplaza 'N/A' con '0' en todas partes"

Herramienta	Descripción	Ejemplo
`share_spreadsheet`	Compartir o hacer público	"Haz pública esta hoja de cálculo"

Ejemplos de uso

Ejemplo 1: Crear un informe de ventas

User: Create a sales report in spreadsheet abc123

Claude will:
1. get_spreadsheet_info("abc123") - Check existing sheets
2. create_sheet("abc123", "Sales Report") - Create new sheet
3. write_cells("abc123", "Sales Report!A1", '[["Product", "Q1", "Q2", "Q3", "Q4", "Total"]]')
4. write_cells("abc123", "Sales Report!A2", '[["Widget", 100, 150, 200, 180, "=SUM(B2:E2)"]]')
5. format_cells(..., bold=True, background_color="#4285F4") - Format header
6. create_chart(..., "COLUMN", "Quarterly Sales") - Add chart

Ejemplo 2: Analizar datos existentes

User: Summarize the data in Sheet1

Claude will:
1. read_cells("abc123", "Sheet1!A1:Z1") - Read headers
2. get_last_row("abc123", "Sheet1", "A") - Find data extent
3. read_cells("abc123", "Sheet1!A1:D100") - Read all data
4. Provide summary and insights

Ejemplo 3: Dar formato a una tabla

User: Make the spreadsheet look professional

Claude will:
1. format_cells(..., bold=True, background_color="#1a73e8", font_color="#FFFFFF") - Header
2. set_column_width(..., 150) - Adjust widths
3. format_cells(..., alignment="CENTER") - Center data

Referencia de notación A1

Notación	Descripción
`Sheet1!A1:D10`	Celdas A1 a D10 en la Hoja1
`Sheet1!A:A`	Columna A completa en la Hoja1
`Sheet1!1:5`	Filas 1-5 en la Hoja1
`A1:B10`	Rango en la primera hoja visible
`'My Sheet'!A1`	Nombre de hoja con espacios (usa comillas)

Referencia de índices

Filas: basado en 0 en formato (Fila 1 = índice 0)
Columnas: basado en 0 (A=0, B=1, C=2, D=3...)
sheet_id: ID numérico de list_sheets o get_spreadsheet_info

Fórmulas comunes

=SUM(A1:A10)           Sum values
=AVERAGE(B:B)          Average entire column
=COUNT(A:A)            Count numbers
=COUNTA(A:A)           Count non-empty cells
=MAX(A1:A100)          Maximum value
=MIN(A1:A100)          Minimum value
=VLOOKUP(A1,B:C,2,0)   Lookup value
=IF(A1>100,"High","Low") Conditional
=CONCATENATE(A1," ",B1)  Join text
=TODAY()               Current date
=NOW()                 Current date/time

Solución de problemas

Error	Solución
"Credenciales de cuenta de servicio no encontradas"	Verifica que `credentials/service-account.json` exista
"403 Prohibido"	Comparte la hoja de cálculo con el correo de la cuenta de servicio
"API no habilitada"	Habilita las APIs de Sheets y Drive en Google Cloud Console
"Cuota excedida"	Espera un minuto, estás alcanzando los límites de tasa

Estructura de archivos

spreadsheet-mcp/
├── pyproject.toml
├── README.md
├── credentials/
│   └── service-account.json  (your key, gitignored)
└── src/spreadsheet_mcp/
    ├── __init__.py
    ├── auth.py              # Google authentication
    ├── sheets_client.py     # API wrapper (1000+ lines)
    └── server.py            # MCP server (27 tools)

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una solicitud de extracción (Pull Request).

Autor

@dudegladiator

Licencia

MIT