Servidor MCP Google Sheets

Lee, escribe y gestiona Google Sheets desde Claude Desktop, Claude Code y cualquier cliente de IA compatible con el Protocolo de Contexto de Modelo (MCP).

Un servidor Model Context Protocol (MCP) ligero y listo para producción que expone la API de Google Sheets a Claude y otros agentes LLM. Automatiza flujos de trabajo con hojas de cálculo, crea herramientas para agentes de IA que registren en hojas, sincroniza tuberías de datos con las hojas de tu equipo o deja que Claude edite un documento por ti, todo con un único servidor MCP.

Tabla de contenidos

• Por qué

• Características

• Inicio rápido

• Configuración

  • 1. Crear un proyecto de Google Cloud

  • 2. Habilitar la API de Sheets

  • 3. Crear credenciales OAuth 2.0

  • 4. Instalar el servidor

  • 5. Autorizar

• Registrar con tu cliente MCP

  • Claude Desktop

  • Claude Code

• Herramientas disponibles

• Ejemplos de uso

• Configuración

• Seguridad

• Solución de problemas

• Desarrollo

• Licencia

Por qué

Si alguna vez quisiste que Claude actualice una hoja de cálculo de Google (un rastreador de trabajos, un registro de hábitos, un panel de proyecto) sin cambiar de ventana, este servidor te da la herramienta que faltaba. Es el complemento natural del conector oficial de Google Drive de Anthropic (que lee archivos pero no puede escribir celdas).

Flujos de trabajo comunes:

• Deja que Claude añada filas a una hoja de seguimiento de solicitudes de empleo mientras aplicas.

• Sincroniza una lista de lectura de investigación, una retro semanal o un registro de estudio IELTS.

• Dale a un agente de IA una salida estructurada y auditable a una hoja de cálculo.

• Automatiza paneles financieros o de operaciones a partir de indicaciones en lenguaje natural.

Características

• ✅ Lee cualquier rango en notación A1.

• ✅ Actualiza valores de celdas con parseo RAW o USER_ENTERED.

• ✅ Añade filas a cualquier hoja (ideal para registro).

• ✅ Limpia rangos sin eliminar formato.

• ✅ Actualización por lotes de múltiples rangos en una sola llamada.

• ✅ Inspecciona metadatos de la hoja de cálculo (pestañas, dimensiones).

• 🔐 OAuth 2.0 con almacenamiento local de tokens y renovación automática.

• 📦 TypeScript, módulos ES, dependencias mínimas.

• 🖥️ Funciona con Claude Desktop, Claude Code y cualquier cliente MCP sobre stdio.

Inicio rápido

# 1. Clone
git clone https://github.com/yangchoi/mcp-google-sheets.git
cd mcp-google-sheets

# 2. Install and build
npm install
npm run build

# 3. Put your Google Cloud OAuth credentials.json here
mkdir -p ~/.config/mcp-google-sheets
cp /path/to/downloaded-credentials.json ~/.config/mcp-google-sheets/credentials.json

# 4. Authorize (opens browser once)
npm run auth

# 5. Register with Claude — see below

Configuración

1. Crear un proyecto de Google Cloud

• Abre Google Cloud Console.

• Haz clic en Nuevo Proyecto → asígnale cualquier nombre (por ejemplo, mcp-sheets).

2. Habilitar la API de Sheets

• En tu proyecto, abre Google Sheets API.

• Haz clic en Habilitar.

3. Crear credenciales OAuth 2.0

• Abre Credenciales.

• Haz clic en Crear Credenciales → ID de cliente OAuth.

• Si se te solicita, configura primero la pantalla de consentimiento OAuth:

  • Tipo de usuario: Externo (a menos que estés en un Workspace con opción Interno disponible).

  • Añádete como usuario de prueba mientras la aplicación esté en modo Prueba.

  • Los alcances se pueden dejar vacíos en la pantalla de consentimiento; la aplicación los solicitará en tiempo de ejecución.

• De vuelta en Crear ID de cliente OAuth:

  • Tipo de aplicación: Aplicación de escritorio.

  • Nombre: cualquier cosa (por ejemplo, mcp-google-sheets).

• Haz clic en Descargar JSON y guárdalo. Este es tu credentials.json.

Mueve el archivo al directorio de configuración predeterminado:

mkdir -p ~/.config/mcp-google-sheets
mv ~/Downloads/client_secret_*.json ~/.config/mcp-google-sheets/credentials.json

(O configura GOOGLE_SHEETS_CREDENTIALS_PATH para que apunte a otro lugar; consulta Configuración.)

4. Instalar el servidor

git clone https://github.com/yangchoi/mcp-google-sheets.git
cd mcp-google-sheets
npm install
npm run build

5. Autorizar

Ejecuta el flujo OAuth de una sola vez. Se abrirá tu navegador, apruebas el acceso a tus propias hojas y el token resultante se almacena en ~/.config/mcp-google-sheets/token.json.

npm run auth

Deberías ver Authorization complete. Token saved. en la terminal.

Registrar con tu cliente MCP

Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows) y añade:

{
  "mcpServers": {
    "google-sheets": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-google-sheets/dist/index.js"]
    }
  }
}

Reinicia Claude Desktop. Las herramientas de Sheets aparecerán en el selector de herramientas.

Claude Code

Añádelo a tu configuración MCP de Claude Code (típicamente ~/.claude/settings.json bajo mcpServers):

{
  "mcpServers": {
    "google-sheets": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-google-sheets/dist/index.js"]
    }
  }
}

Reinicia Claude Code. Confirma que las herramientas se carguen mediante /mcp.

Herramientas disponibles

Todas las herramientas toman spreadsheetId (que se encuentra en la URL de la hoja entre /d/ y /edit).

Ejemplos de uso

Indica a Claude:

"Mira la hoja de cálculo 1abcXYZ... y añade una nueva fila a la hoja Applications: Legora, Stockholm, Legal AI, 2026-08-18, pending."

Claude llamará a get_spreadsheet_metadata para encontrar la hoja, luego append_row con los valores.

O lee + resume:

"Lee las primeras 20 filas de la hoja Applications en 1abcXYZ... y dime cuántas están aún pendientes."

Claude llama a read_range en Applications!A1:F20, luego razona sobre el array devuelto.

Configuración

Variables de entorno (todas opcionales):

Seguridad

• credentials.json y token.json son solo locales y nunca se transmiten a ningún lugar excepto a los servidores OAuth de Google.

• Ambos archivos están cubiertos por .gitignore; no los confirmes en el control de versiones.

• El servidor solo solicita el alcance spreadsheets: sin acceso a Drive, sin Gmail, sin calendario.

• La renovación del token ocurre automáticamente; no se expone ningún token de acceso de larga duración.

• Ejecutar el servidor no requiere ningún puerto de escucha de red en estado estable (el puerto temporal 47319 se usa solo durante la devolución de llamada OAuth inicial y se cierra inmediatamente después).

Solución de problemas

credentials.json not found — te perdiste el paso 3–4. Verifica la ruta.

Error: access_denied durante OAuth — tu cuenta de Google no está listada como usuario de prueba en la pantalla de consentimiento OAuth. Ve a Pantalla de consentimiento OAuth → añade tu correo electrónico bajo Usuarios de prueba.

insufficient permission al llamar a una herramienta — el token se creó con un alcance más pequeño. Elimina token.json y vuelve a ejecutar npm run auth.

La herramienta no aparece en Claude — confirma que la ruta en tu configuración MCP sea absoluta y apunte a dist/index.js (no a src/index.ts). Asegúrate de haber ejecutado npm run build.

No stored token al iniciar el servidor — te saltaste el paso 5. Ejecuta npm run auth.

Desarrollo

npm install
npm run dev      # tsc --watch
npm run build    # produces dist/
npm run start    # runs dist/index.js on stdio

Las contribuciones son bienvenidas. Este es un núcleo mínimo; se agradecen las solicitudes de extracción para actualizaciones estructurales (spreadsheets.batchUpdate para formato, añadir hojas, filtros, rangos protegidos).

Licencia

MIT