mcp-google-sheets: Un servidor MCP de Hojas de cálculo de Google

Este servidor MCP se integra con Google Drive y Google Sheets para permitir la creación y modificación de hojas de cálculo.

Descripción general

Un servidor de Protocolo de Contexto de Modelo para interactuar con Hojas de Cálculo de Google. Este servidor proporciona herramientas para crear, leer, actualizar y administrar hojas de cálculo mediante la API de Hojas de Cálculo de Google.

Herramientas

get_sheet_data
- Obtener datos de una hoja específica en una hoja de cálculo de Google
- Aporte:
  - spreadsheet_id (cadena): El ID de la hoja de cálculo (que se encuentra en la URL)
  - sheet (cadena): El nombre de la hoja
  - range (cadena opcional): rango de celdas en notación A1 (por ejemplo, 'A1:C10')
- Devuelve: una matriz 2D de los datos de la hoja
update_cells
- Actualizar celdas en una hoja de cálculo de Google
- Aporte:
  - spreadsheet_id (cadena): El ID de la hoja de cálculo
  - sheet (cadena): El nombre de la hoja
  - range (cadena): rango de celdas en notación A1
  - data (matriz 2D): Valores a actualizar
- Devuelve: Resultado de la operación de actualización
batch_update_cells
- Actualización por lotes de varios rangos en una hoja de cálculo de Google
- Aporte:
  - spreadsheet_id (cadena): El ID de la hoja de cálculo
  - sheet (cadena): El nombre de la hoja
  - ranges (objeto): Diccionario que asigna cadenas de rango a matrices 2D de valores
- Devuelve: Resultado de la operación de actualización por lotes
list_sheets
- Enumerar todas las hojas en una hoja de cálculo de Google
- Aporte:
  - spreadsheet_id (cadena): El ID de la hoja de cálculo
- Devuelve: Lista de nombres de hojas
list_spreadsheets
- Enumere todas las hojas de cálculo en la carpeta de Google Drive configurada
- Devuelve: Lista de hojas de cálculo con su ID y título
- Nota: Si se utiliza la autenticación de cuenta de servicio, se mostrarán las hojas de cálculo en la carpeta compartida.
create_spreadsheet
- Crear una nueva hoja de cálculo de Google
- Aporte:
  - title (cadena): el título de la nueva hoja de cálculo
- Devuelve: Información sobre la hoja de cálculo recién creada, incluido su ID
- Nota: Al utilizar la autenticación de cuenta de servicio con un ID de carpeta configurado, la hoja de cálculo se creará en esa carpeta
create_sheet
- Crear una nueva pestaña de hoja en una hoja de cálculo de Google existente
- Aporte:
  - spreadsheet_id (cadena): El ID de la hoja de cálculo
  - title (cadena): el título de la nueva hoja
- Devuelve: Información sobre la hoja recién creada
Herramientas adicionales: add_rows , add_columns , copy_sheet , rename_sheet

Recursos

spreadsheet://{spreadsheet_id}/info
- Obtenga información básica sobre una hoja de cálculo de Google
- Devuelve: cadena JSON con información de la hoja de cálculo

Instalación y configuración

El servidor requiere cierta configuración en Google Cloud Platform y la elección de un método de autenticación antes de ejecutarse.

Configuración de Google Cloud Platform (obligatoria para todos los métodos)

Crear un proyecto de Google Cloud Platform:
- Ir a la consola de Google Cloud
- Crea un nuevo proyecto o selecciona uno existente
- Habilitar la API de Hojas de cálculo de Google y la API de Google Drive

Elija un método de autenticación

Puede utilizar uno de dos métodos de autenticación:

Método 1: Autenticación de cuenta de servicio (recomendado, no interactivo)

Las cuentas de servicio proporcionan autenticación sin interfaz gráfica, sin indicaciones del navegador, ideal para entornos automatizados o de servidor. Sus ventajas incluyen:

No se necesita interacción del navegador para la autenticación
Funciona bien en entornos sin cabeza
La autenticación no caduca con tanta frecuencia como los tokens OAuth
Perfecto para implementaciones de servidores y automatización.

Pasos de configuración:

Crear una cuenta de servicio:
- Vaya a Google Cloud Console → IAM y administración → Cuentas de servicio
- Cree una nueva cuenta de servicio con un nombre descriptivo
- Otórgale los roles apropiados (para acceder a Hojas de cálculo de Google)
- Crear y descargar un archivo de clave JSON
Crea una carpeta dedicada en Google Drive para compartir con la cuenta de servicio:
- Vaya a Google Drive y cree una nueva carpeta (por ejemplo, "Claude Sheets")
- Anote el ID de la carpeta desde su URL: https://drive.google.com/drive/folders/FOLDER_ID_HERE
- Haga clic derecho en la carpeta y seleccione "Compartir".
- Compártalo con la dirección de correo electrónico de la cuenta de servicio (que se encuentra en el archivo JSON como client_email )
- Dale acceso de "Editor"
Establezca estas variables de entorno:
- SERVICE_ACCOUNT_PATH : Ruta al archivo de clave JSON de la cuenta de servicio
- DRIVE_FOLDER_ID : ID de la carpeta de Google Drive compartida con la cuenta de servicio

Método 2: Autenticación OAuth 2.0 (interactiva)

Este método requiere la interacción del navegador para la primera configuración y es adecuado para uso personal o desarrollo.

Configurar OAuth para su proyecto:
- Configurar la pantalla de consentimiento de OAuth
- Crear credenciales de ID de cliente OAuth 2.0 (tipo de aplicación de escritorio)
- Descargue el archivo JSON de credenciales y guárdelo como credentials.json
Establezca estas variables de entorno:
- CREDENTIALS_PATH : Ruta al archivo de credenciales OAuth descargado (predeterminado: credentials.json )
- TOKEN_PATH : Ruta donde se almacenará el token de autenticación (predeterminado: token.json )

Configuración de variables de entorno

Para Linux/Mac:

# For service account authentication (recommended)
export SERVICE_ACCOUNT_PATH=/path/to/your/service-account-key.json
export DRIVE_FOLDER_ID=your_shared_folder_id_here

# OR for OAuth authentication
export CREDENTIALS_PATH=/path/to/your/credentials.json
export TOKEN_PATH=/path/to/your/token.json

Para Windows:

# For service account authentication (recommended)
set SERVICE_ACCOUNT_PATH=C:\path\to\your\service-account-key.json
set DRIVE_FOLDER_ID=your_shared_folder_id_here

# OR for OAuth authentication
set CREDENTIALS_PATH=C:\path\to\your\credentials.json
set TOKEN_PATH=C:\path\to\your\token.json

Ejecución del servidor

Método 1: Uso de uvx (recomendado para uso normal)

Al usar uvx , puedes ejecutar el servidor directamente sin instalación:

# Set environment variables first, then run the server
uvx mcp-google-sheets

Método 2: Para desarrollo y modificaciones

Si desea modificar y desarrollar el servidor:

Clonar el repositorio:

git clone https://github.com/yourusername/mcp-google-sheets.git
cd mcp-google-sheets

Correr con uv:

# Set environment variables first, then run
uv run mcp-google-sheets

Proceso de autenticación

El servidor selecciona automáticamente el método de autenticación en función de las variables de entorno:

Primero, verifica las credenciales de la cuenta de servicio (no interactiva)
Si la autenticación de la cuenta de servicio falla o no está configurada, se recurre al flujo de OAuth.

Con la autenticación de la cuenta de servicio, no se necesita interacción con el navegador y el servidor operará directamente en las hojas de cálculo de la carpeta compartida de Google Drive.

Con la autenticación OAuth, la primera vez que uses el servidor, se abrirá una ventana del navegador para autenticarte con tu cuenta de Google. Tras la autenticación, se guardará un token en la ubicación especificada por la variable de entorno TOKEN_PATH .

Uso con Claude Desktop

Agregue esto a su claude_desktop_config.json :

"mcpServers": {
  "google-sheets": {
    "command": "uvx",
    "args": ["mcp-google-sheets"],
    "env": {
      "SERVICE_ACCOUNT_PATH": "/path/to/your/service-account-key.json",
      "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
    }
  }
}

"mcpServers": {
  "google-sheets": {
    "command": "uvx",
    "args": ["mcp-google-sheets"],
    "env": {
      "CREDENTIALS_PATH": "/path/to/your/credentials.json",
      "TOKEN_PATH": "/path/to/your/token.json"
    }
  }
}

"mcpServers": {
  "mcp-google-sheets": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/mcp-google-sheets",
      "run",
      "mcp-google-sheets"
    ],
    "env": {
      "SERVICE_ACCOUNT_PATH": "/path/to/mcp-google-sheets/service-account-key.json",
      "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      // OR for OAuth: 
      // "CREDENTIALS_PATH": "/path/to/mcp-google-sheets/credentials.json",
      // "TOKEN_PATH": "/path/to/mcp-google-sheets/token.json"
    },
    "disabled": false
  }
}

Ejemplos de indicaciones para Claude

Una vez que el servidor MCP esté conectado a Claude, puedes usar indicaciones como estas:

"Enumerar todas las hojas de cálculo en mi carpeta compartida"
"Crea una nueva hoja de cálculo titulada 'Presupuesto 2024'"
Obtener los datos de la Hoja 1 en mi hoja de cálculo con ID 1A2B3C4D5E6F7G8H
"Agregar 3 filas al comienzo de la Hoja 2 en mi hoja de cálculo"
"Actualizar las celdas A1:B2 en mi hoja de cálculo con los valores [[1, 2], [3, 4]]"
"Enumerar todas las hojas de mi hoja de cálculo de Presupuesto"
Copia la hoja "Marzo" de mi hoja de cálculo del primer trimestre a mi hoja de cálculo anual y cámbiale el nombre a "T1-Marzo".
"Agregar una nueva hoja llamada 'T4' a mi hoja de cálculo de Presupuesto Anual"

Licencia

Este servidor MCP cuenta con la licencia MIT. Esto significa que puede usar, modificar y distribuir el software libremente, sujeto a los términos y condiciones de la licencia MIT. Para más detalles, consulte el archivo de LICENCIA en el repositorio del proyecto.

Créditos

Este proyecto se inspiró en el repositorio kazz187/mcp-google-spreadsheet y se portó a Python usando FastMCP.

mcp-google-sheets

Integrations