google-sheets-mcp

MCP server para gestionar Google Sheets y Drive desde Claude Desktop.
Desarrollado por Vanguard Strategy.

Instalación en Claude Desktop

1. Setup inicial (una sola vez)

Crea las credenciales OAuth en Google Cloud y guárdalas localmente:

npx koder-sheets-mcp setup

El asistente te guiará paso a paso:

1. Ve a Google Cloud Console
2. Crea un proyecto (o selecciona uno existente)
3. Habilita las APIs: Google Sheets API y Google Drive API
4. Ve a APIs y servicios → Credenciales → Crear credenciales → ID de cliente OAuth 2.0
   • Tipo de aplicación: Aplicación de escritorio
5. Pega el client_id y client_secret cuando el asistente lo pida

Las credenciales se guardan en ~/.vanguard-sheets/credentials.json — no necesitas configurarlas en Claude Desktop.

2. Agregar el MCP a Claude Desktop

Opción A — comando rápido (Claude Code CLI):

claude mcp add-json google-sheets '{"type":"stdio","command":"npx","args":["-y","koder-sheets-mcp@latest"]}'

Opción B — editar el archivo de config manualmente:

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

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": ["-y", "koder-sheets-mcp@latest"]
    }
  }
}

Reinicia Claude Desktop.

3. Conectar tu cuenta de Google

La primera vez que uses el MCP, pide a Claude que ejecute sheets_oauth_start.
Se abrirá un link en el browser — inicia sesión con tu cuenta de Google y autoriza el acceso.

Los tokens se guardan en ~/.vanguard-sheets/tokens.json y se renuevan automáticamente.

Configuración avanzada (opcional)

Variables de entorno (alternativa a setup)

Si prefieres no usar el asistente, puedes pasar las credenciales via env vars:

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": ["-y", "google-sheets-mcp@latest"],
      "env": {
        "GOOGLE_CLIENT_ID": "TU_CLIENT_ID",
        "GOOGLE_CLIENT_SECRET": "TU_CLIENT_SECRET"
      }
    }
  }
}

Plantillas Vanguard

Para usar sheets_copy_template con las plantillas base de Vanguard,
agrega los IDs de cada planilla plantilla:

"env": {
  "VANGUARD_TEMPLATE_CONTROL_TOTAL": "<spreadsheetId>",
  "VANGUARD_TEMPLATE_CONTROL_TOTAL_PRO": "<spreadsheetId>",
  "VANGUARD_TEMPLATE_FLUJO_CAJA_PROFESIONAL": "<spreadsheetId>",
  "VANGUARD_TEMPLATE_FLUJO_CAJA_PREMIUM": "<spreadsheetId>",
  "VANGUARD_TEMPLATE_CAPITAL_PRO": "<spreadsheetId>",
  "VANGUARD_TEMPLATE_COTIZADOR_PRO": "<spreadsheetId>",
  "VANGUARD_TEMPLATE_GESTOR_OC_PRO": "<spreadsheetId>",
  "VANGUARD_TEMPLATE_SISTEMA_CREDITOS_PRO": "<spreadsheetId>"
}

Herramientas disponibles

| Grupo | Tool | Descripción | |---|---|---| | Auth | sheets_oauth_start | Iniciar autorización OAuth con Google | | Auth | sheets_oauth_status | Ver estado de la sesión | | Auth | sheets_oauth_revoke | Revocar acceso | | Planillas | sheets_create_spreadsheet | Crear planilla nueva | | Planillas | sheets_copy_template | Copiar desde plantilla Vanguard o cualquier planilla | | Planillas | sheets_get_info | Obtener metadatos y lista de hojas | | Planillas | sheets_list_spreadsheets | Listar planillas en Drive | | Hojas | sheets_add_sheet | Agregar hoja (tab) | | Hojas | sheets_rename_sheet | Renombrar hoja | | Hojas | sheets_delete_sheet | Eliminar hoja | | Hojas | sheets_duplicate_sheet | Duplicar hoja | | Hojas | sheets_freeze | Congelar filas/columnas | | Datos | sheets_read_range | Leer celdas | | Datos | sheets_write_range | Escribir celdas | | Datos | sheets_append_rows | Agregar filas al final | | Datos | sheets_clear_range | Limpiar celdas | | Datos | sheets_batch_write | Escribir múltiples rangos de una vez | | Formato | sheets_format_range | Aplicar colores, fuentes, bordes, formato numérico | | Formato | sheets_merge_cells | Combinar celdas | | Formato | sheets_set_column_width | Ajustar ancho de columnas | | Formato | sheets_protect_range | Proteger rango o hoja | | Gráficos | sheets_add_chart | Crear gráfico | | Gráficos | sheets_delete_chart | Eliminar gráfico | | Drive | sheets_share_file | Compartir planilla con usuario | | Drive | sheets_list_permissions | Ver permisos | | Drive | sheets_revoke_permission | Revocar acceso de un usuario | | Drive | sheets_make_public | Hacer planilla pública (solo lectura) | | Drive | sheets_create_folder | Crear carpeta en Drive | | Drive | sheets_list_folders | Listar carpetas | | Drive | sheets_delete_file | Eliminar archivo o carpeta |

Desarrollo local

git clone https://github.com/vanguard/google-sheets-mcp
cd google-sheets-mcp
npm install
npm run dev       # modo watch con tsx
npm run build     # compilar a dist/
npm start         # ejecutar desde dist/
node dist/index.js setup  # setup de credenciales

Estructura del proyecto

src/
├── index.ts              # Entry point + subcomando setup
├── server.ts             # McpServer + registro de todos los tools
├── auth/
│   └── oauth.ts          # Flujo OAuth 2.0 + token storage
├── cli/
│   └── setup.ts          # Asistente de setup inicial
├── config/
│   ├── constants.ts      # Constantes globales
│   └── credentials.ts    # Carga de credenciales (archivo local o env vars)
├── tools/
│   ├── auth.ts           # Tools: oauth_start, oauth_status, oauth_revoke
│   ├── spreadsheet.ts    # Tools: create, copy_template, get_info, list
│   ├── sheets.ts         # Tools: add, rename, delete, duplicate, freeze
│   ├── data.ts           # Tools: read, write, append, clear, batch_write
│   ├── format.ts         # Tools: format_range, merge, column_width, protect
│   ├── charts.ts         # Tools: add_chart, delete_chart
│   └── drive.ts          # Tools: share, permissions, folders
├── services/
│   ├── sheets-client.ts  # Wrapper de googleapis Sheets v4
│   └── drive-client.ts   # Wrapper de googleapis Drive v3
├── schemas/
│   └── index.ts          # Zod schemas reutilizables
├── types/
│   └── index.ts          # TypeScript interfaces

Licencia

MIT — © 2026 Vanguard Strategy