gsheets-mcp

Un servidor MCP (Model Context Protocol) local que permite a Claude leer y escribir en tus Google Sheets a través de la API v4 de Google Sheets.

Se ejecuta completamente en tu propia máquina. Te autenticas con tu propia cuenta de Google mediante OAuth2 (el flujo de "aplicación instalada" / escritorio), y tus datos nunca pasan por ningún servidor de terceros.

Gratuito y de código abierto bajo la Licencia MIT. Sin telemetría, sin servidores de terceros.

🌐 Sitio web: https://gsheets-mcp.trombella.org/

Lo que obtienes

La mayoría de las herramientas toman un ID de hoja de cálculo — la cadena larga en la URL de una hoja: https://docs.google.com/spreadsheets/d/<ESTE_ES_EL_ID>/edit. También puedes descubrir los IDs con list_spreadsheets en lugar de copiarlos manualmente.

Related MCP server: sheetsdb-mcp-server

Requisitos previos

• Node.js 18+ (node --version).

• Una cuenta de Google.

Parte 1 — Configurar Google Cloud (una vez)

Necesitas un cliente OAuth de "aplicación de escritorio" para que el servidor pueda solicitar tu permiso para acceder a tus hojas.

1. Crear un proyecto de Google Cloud

1. Ve a https://console.cloud.google.com/.

2. Barra superior → menú desplegable de proyectos → Nuevo proyecto. Ponle un nombre (p. ej. gsheets-mcp) y créalo. Asegúrate de que esté seleccionado.

2. Habilitar las APIs

1. Ve a APIs y servicios → Biblioteca (https://console.cloud.google.com/apis/library).

2. Busca Google Sheets API, ábrela, haz clic en Habilitar.

3. Busca Google Drive API, ábrela, haz clic en Habilitar.

La API de Drive se usa solo por list_spreadsheets para enumerar tus hojas, mediante el alcance de solo lectura drive.readonly. No se usa para modificar, mover o eliminar archivos.

3. Configurar la pantalla de consentimiento de OAuth

1. Ve a APIs y servicios → Pantalla de consentimiento de OAuth.

2. Tipo de usuario: Externo → Crear. (Interno solo está disponible en organizaciones de Google Workspace).

3. Completa los campos obligatorios: Nombre de la aplicación (p. ej. gsheets-mcp), tu correo electrónico como Correo de asistencia al usuario y Contacto de desarrollador. Puedes dejar el resto en blanco. Guardar y continuar.

4. Alcances: puedes omitir agregar alcances aquí (la aplicación los solicita al iniciar sesión). Guardar y continuar.

5. Usuarios de prueba: haz clic en Agregar usuarios y agrega tu propio correo de Google. Esto es obligatorio: en modo "Prueba", solo los usuarios de prueba listados pueden autorizar la aplicación. Guardar y continuar.

6. Deja la aplicación en modo Prueba. Eso es suficiente para uso personal y nunca caduca para tu propia cuenta de usuario de prueba. (Publicar en "Producción" activaría la verificación de aplicaciones de Google, que no necesitas aquí).

4. Crear las credenciales del cliente OAuth

1. Ve a APIs y servicios → Credenciales.

2. Crear credenciales → ID de cliente OAuth.

3. Tipo de aplicación: Aplicación de escritorio. Ponle un nombre (p. ej. gsheets-mcp desktop). Crear.

4. En el diálogo de confirmación, haz clic en Descargar JSON. Este archivo contiene tu client_id y client_secret.

5. Colocar el archivo de credenciales

Guarda el archivo descargado como credentials.json en el directorio de configuración:

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

Mantén este archivo privado: está ignorado por git. Puedes sobrescribir su ubicación con la variable de entorno GSHEETS_MCP_CREDENTIALS (consulta .env.example).

Parte 2 — Instalar y compilar

Desde la carpeta del proyecto:

npm install
npm run build

Parte 3 — Iniciar sesión (una vez)

Ejecuta el inicio de sesión interactivo. Abre tu navegador en la pantalla de consentimiento de Google; aprueba el acceso y el token se guarda en ~/.config/gsheets-mcp/token.json (se actualiza automáticamente a partir de entonces).

npm run login
# equivalently: node dist/index.js login

Debido a que la aplicación está en modo Prueba, Google muestra una advertencia de "Google no ha verificado esta aplicación". Esto es esperado para tu propia aplicación: haz clic en Avanzado → Ir a gsheets-mcp (no seguro) y continúa. Luego concede los dos permisos solicitados (ver más abajo).

Cuando veas ✅ Autorización completa en la terminal, habrás terminado.

Alcances solicitados:

• https://www.googleapis.com/auth/spreadsheets — lectura/escritura de tus hojas de cálculo.

• https://www.googleapis.com/auth/drive.readonly — solo lectura, usado solo por list_spreadsheets para enumerar tus hojas. No puede modificar ni eliminar archivos.

Para revocar el acceso en cualquier momento, visita https://myaccount.google.com/permissions.

Nota: si actualizas el servidor y los alcances solicitados cambian, debes ejecutar npm run login de nuevo: un consentimiento previamente otorgado no cubre nuevos alcances. Lo mismo aplica por máquina (cada computadora almacena su propio token).

Parte 4 — Agregar el servidor a Claude Desktop

Abre el archivo de configuración de Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Agrega una entrada gsheets bajo mcpServers, apuntando al punto de entrada compilado. Usa la ruta absoluta a dist/index.js en este proyecto:

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

Guarda el archivo y cierra y vuelve a abrir completamente Claude Desktop. Ahora deberías ver las herramientas gsheets disponibles. Prueba preguntarle a Claude algo como:

"Lista mis Google Sheets y luego lee A1:C5 de la hoja llamada 'Presupuesto'."

Usarlo con Claude Code

claude mcp add gsheets -- node /absolute/path/to/google-sheets-mcp/dist/index.js

Ejemplos de uso (qué preguntarle a Claude)

• Listar: "Lista mis Google Sheets" / "Encuentra mis hojas de cálculo cuyo nombre contenga 'presupuesto'."

• Información: "¿Qué pestañas tiene la hoja de cálculo <ID>?" (devuelve los nombres exactos de las pestañas para usar).

• Leer: "Lee el rango Foglio1!A1:D10 de la hoja de cálculo <ID>."

• Actualizar: "Pon los valores [[\"Nombre\",\"Puntuación\"],[\"Ada\",42]] comenzando en Foglio1!A1 en la hoja de cálculo <ID>."

• Añadir: "Añade la fila [\"Grace\", 99] a Foglio1 en la hoja de cálculo <ID>."

⚠️ Nota: los nombres de las pestañas están localizados

Los rangos usan el nombre de la pestaña (hoja), p. ej. Sheet1!A1:D10. Pero el nombre de pestaña predeterminado depende del idioma de tu cuenta de Google: es Sheet1 en inglés, Foglio1 en italiano, Hoja1 en español, Feuille1 en francés, etc. Usar el nombre incorrecto devuelve Unable to parse range: ….

Si no estás seguro del nombre real de la pestaña, abre la hoja y lee la etiqueta de la pestaña en la parte inferior, o simplemente pídele a Claude que lea toda la hoja pasando solo el nombre de la pestaña como rango (p. ej. Foglio1). Una herramienta dedicada get_sheet_info que liste los nombres exactos de las pestañas está en la hoja de ruta.

Referencia de configuración

Todo es opcional; los valores predeterminados funcionan sin configuración adicional. Consulta .env.example.

Para el modo sin interfaz / HTTP (ver más abajo) puedes proporcionar credenciales mediante variables de entorno:

Uso remoto / móvil (avanzado)

El transporte predeterminado es stdio (local). El servidor también puede ejecutarse como un conector MCP remoto sobre HTTP para que puedas acceder a él desde clientes que no pueden lanzar un proceso local — p. ej. la aplicación móvil de Claude:

MCP_AUTH_TOKEN=$(openssl rand -hex 32) npm run serve:http   # listens on :8000/mcp

Cada solicitud debe enviar Authorization: Bearer <MCP_AUTH_TOKEN>. Debido a que este endpoint puede escribir en tus hojas de cálculo, colócalo siempre detrás de una puerta de red (Cloudflare Access, VPN) además del token Bearer — nunca lo expongas directamente en internet.

Un add-on de Home Assistant OS listo para usar para una configuración personal siempre activa (detrás de un Cloudflare Tunnel) vive en ha-addon/gsheets-mcp/ — consulta su DOCS.md para el paso a paso completo.

Solución de problemas

• "Not authenticated. Run the one-time login first" — aún no has iniciado sesión, o el archivo de token falta. Ejecuta npm run login.

• "OAuth client credentials not found" — credentials.json no está donde el servidor lo espera. Revisa la Parte 1, paso 5.

• 403 access_denied en el navegador — tu cuenta de Google no está listada como usuario de prueba. Agrégalo en Pantalla de consentimiento de OAuth → Usuarios de prueba (Parte 1, paso 3.5).

• "Request had insufficient authentication scopes" — tu token guardado es anterior a un cambio de alcance (p. ej. list_spreadsheets necesita drive.readonly). Ejecuta npm run login de nuevo para volver a dar consentimiento.

• Unable to parse range: … — el nombre de la pestaña es incorrecto. Los nombres de las pestañas están localizados (Foglio1 en italiano, Sheet1 en inglés). Usa get_sheet_info para ver los nombres exactos.

• Advertencia de no refresh_token — revoca la aplicación en https://myaccount.google.com/permissions y ejecuta npm run login de nuevo.

• Las herramientas no aparecen en Claude Desktop — confirma que la ruta en claude_desktop_config.json sea absoluta y apunte a dist/index.js, que ejecutaste npm run build y que reiniciaste completamente Claude Desktop.

Desarrollo

npm run build       # compile to dist/
npm run watch       # recompile on change
npm run typecheck   # type-check without emitting

Estructura del código fuente: src/index.ts (punto de entrada), src/auth.ts (OAuth), src/sheetsClient.ts y src/driveClient.ts (envoltorios de API), src/tools/* (un archivo por herramienta MCP).

Licencia

Publicado bajo la Licencia MIT. Eres libre de usarlo, modificarlo y distribuirlo. Si te ahorra tiempo, puedes apoyar el desarrollo con un café — consulta el sitio web para el enlace. ☕

No afiliado ni respaldado por Google. "Google Sheets" es una marca comercial de Google LLC.