README.md
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, `she |
Tools 16
sheets_read_rangeReads data from a specific range in a Google Sheet.sheets_write_rangeWrites data into a specific range in a Google Sheet.sheets_append_rowsAppends new rows to the end of a sheet.sheets_delete_rowsDeletes rows from a sheet.sheets_get_rowsRetrieves rows as objects.sheets_format_rangeApplies visual formatting to a range of cells.sheets_clear_formatClears all formatting from a range.sheets_get_conditional_rulesLists all conditional formatting rules for a sheet.sheets_add_conditional_ruleAdds a new conditional formatting rule.sheets_delete_conditional_ruleDeletes a conditional formatting rule by index.sheets_clear_conditional_rulesRemoves all conditional formatting rules from a sheet.sheets_list_sheetsLists all sheets within a spreadsheet.sheets_create_sheetCreates a new sheet.sheets_delete_sheetDeletes a sheet.sheets_rename_sheetRenames a sheet.sheets_duplicate_sheetDuplicates a sheet.Environment Variables
GOOGLE_SERVICE_ACCOUNT_PATHrequiredPath to the Google Service Account JSON credentials file.Try it
→Read the data from the 'Sales' sheet in spreadsheet abc123 and summarize the total revenue.
→Add a new row to the 'Inventory' sheet with product name 'Widget' and price 50.
→Apply a green background to the header row of my 'Budget' sheet.
→Create a conditional formatting rule that highlights cells in red if the value is less than 0.
→List all the sheets available in my project spreadsheet.