Sheet-Cello

Servidor MCP de Google Sheets 🚀

Un servidor potente y completo del Protocolo de Contexto de Modelos (MCP) que permite a los agentes de IA interactuar directamente con Google Sheets. Realiza desde actualizaciones simples de celdas hasta análisis de datos complejos y visualizaciones usando lenguaje natural.

---

📂 Estructura del Proyecto

El proyecto está organizado en capas de servicios modulares para facilitar el mantenimiento y la extensibilidad:

• constants/: Configuración centralizada y descripciones de herramientas optimizadas para LLM.
  • constants.py: Definiciones de nombres de herramientas, descripciones y claves de GSheet.
• services/: Lógica central para interactuar con APIs y servicios externos.
• tools/: Implementación de varias funcionalidades de hojas de cálculo:
  • data_analysis/: Ordenamiento, filtrado, tablas dinámicas y extracción de valores únicos.
    • data_operations/: Lectura de rangos, actualizaciones por lotes y entrada de datos en filas/columnas.
    • formattings/: Estilos de texto, colores, alineación, bordes y formatos de números.
    • formulas/: Inserción y evaluación de fórmulas.
    • rows_and_coloumns_operations/: Cambios estructurales (insertar/eliminar/ocultar/mostrar).
    • sheet_operations/: Gestión de hojas (crear, eliminar, renombrar, listar).
    • visualizations/: Creación y actualización dinámica de gráficos.
• utils/: Utilidades auxiliares para normalización de colores y recuperación de hojas de trabajo.
• main.py y server.py: Puntos de entrada e inicialización del servidor MCP.

---

⚙️ Primeros Pasos

1. Requisitos Previos

• Proyecto de Google Cloud con las APIs de Google Sheets y Drive habilitadas.
• Archivo de credenciales JSON de cuenta de servicio colocado en assets/.
• Python 3.10+ instalado.

Paso 2: Crear Proyecto en Google Cloud

• Ve a Consola de Google Cloud
• Crea un nuevo proyecto

Paso 3: Habilitar APIs

Habilita:

• API de Google Sheets
• API de Google Drive

Paso 4: Crear Cuenta de Servicio

• Ve a APIs y Servicios → Credenciales
• Crea una Cuenta de Servicio

Paso 5: Crear Clave de Cuenta de Servicio

• Abre la Cuenta de Servicio
• Crea una clave JSON
• Descarga el archivo (por ejemplo, credentials.json)
• Abre la hoja de Google
• Compártela con el correo de la cuenta de servicio
• Otorga acceso de Editor

Paso 7: Autorizar en Python

mount your credential to assets/ if you running through docker
set SERVICE_FILE_PATH=path to your credential if running locally

2. Verificar la Conexión

1. Verificar que el Servidor Esté Ejecutándose:

   python main.py
   

2. Configuración de Cursor:
   • Abre Configuración de Cursor → Desarrollador → Editar Configuración.
     • Asegúrate de que el servidor esté listado (nombre predeterminado: sheets-cello).
3. Credenciales:
   • Asegúrate de que SERVICE_FILE_PATH en constants/constants.py o como variable de entorno apunte a tu archivo JSON de cuenta de servicio.

---

🛠️ Referencia Exhaustiva de Herramientas

El agente proporciona 46 herramientas especializadas organizadas en las siguientes categorías. Cada herramienta está optimizada para uso con LLM, con descripciones detalladas y ejemplos de uso.

🔌 Conexión y Alcance (1 herramienta)

• select_sheet: Selecciona o activa un libro de Google Sheets diferente por nombre.

📊 Operaciones de Datos (8 herramientas)

• read_range: Recupera valores de un rango rectangular específico (por ejemplo, A1:C10).
• read_batch_ranges: Recupera valores de múltiples rangos no contiguos en una sola llamada.
• read_sheet: Obtiene cada fila y columna poblada de la hoja de trabajo.
• get_cell_value: Recupera el valor de una sola celda específica.
• set_cell_value: Actualiza el valor de una sola celda específica.
• update_row_by_index: Actualiza una fila completa con nuevos datos según el número de fila.
• update_or_insert_column: Actualiza o inserta valores en una columna específica.
• append_data_batch_in_rows: Agrega múltiples filas de datos, encontrando automáticamente el final si es necesario.
• clear_range: Elimina todo el contenido dentro de un rango específico de celdas.

📑 Gestión de Hojas (4 herramientas)

• list_sheets: Recupera una lista de todos los títulos de hojas de trabajo en la hoja de cálculo actual.
• create_sheet: Crea una nueva hoja de trabajo con tamaño opcional de filas/columnas.
• delete_sheet: Elimina una hoja de trabajo existente por su nombre.
• rename_sheet: Actualiza el título de una hoja de trabajo existente.

🎨 Formato y Estilos (12 herramientas)

• set_text_style: Establece negrita, cursiva y tamaño de fuente para un rango.
• set_text_color: Establece el color de primer plano de las celdas usando valores RGB.
• set_background_color: Establece el color de fondo (relleno) de las celdas usando valores RGB.
• set_alignment: Establece la alineación horizontal y/o vertical del texto.
• set_wrap: Controla cómo se ajusta el texto (WRAP, CLIP, OVERFLOW).
• set_borders: Aplica bordes (superior, inferior, izquierdo, derecho) alrededor de un rango.
• set_rotation: Rota el texto dentro de las celdas según un ángulo dado.
• set_number_format: Establece patrones de formato de número, fecha, moneda o porcentaje.
• merge_cells: Fusiona todas las celdas de un rango en una sola celda.
• set_column_width: Establece el ancho de una columna específica en píxeles.
• set_row_height: Establece la altura de una fila específica en píxeles.
• auto_fit_columns: Ajusta automáticamente los anchos de columna según el contenido.

📐 Operaciones de Filas y Columnas (8 herramientas)

• insert_rows: Inserta nuevas filas vacías en un índice específico.
• delete_rows: Elimina un número especificado de filas desde un índice.
• insert_columns: Inserta nuevas columnas vacías en un índice específico.
• delete_columns: Elimina un número especificado de columnas desde un índice.
• hide_rows: Oculta filas específicas de la vista.
• show_rows: Muestra filas previamente ocultas.
• hide_columns: Oculta columnas específicas de la vista.
• show_columns: Muestra columnas previamente ocultas.

🔢 Fórmulas (3 herramientas)

• set_formula_in_cell: Inserta una fórmula de Google Sheets (por ejemplo, =SUM(A1:A10)).
• get_formula_from_cell: Recupera la cadena de fórmula sin procesar de una celda.
• evaluate_formula: Devuelve el resultado numérico o de texto calculado de una fórmula.

📈 Análisis de Datos (6 herramientas)

• sort_range: Ordena un rango por una columna en orden ascendente o descendente.
• filter_data: Aplica criterios de filtrado complejos a un rango.
• remove_duplicates: Elimina filas duplicadas según columnas específicas.
• find_value: Busca un valor específico en un rango o en toda la hoja.
• get_unique_values: Devuelve todos los valores únicos de una columna específica.
• create_gsheet_pivot: Crea un resumen de tabla dinámica en una hoja de destino.

📊 Visualizaciones (3 herramientas)

• create_chart: Crea gráficos de líneas, barras, circulares o de columnas.
• update_chart: Actualiza el título, tipo o posición de un gráfico existente.
• delete_chart: Elimina un gráfico de la hoja de trabajo por su título.

---

🔧 Solución de Problemas

• ¿Las Herramientas MCP No Aparecen?
  1. Asegúrate de que python main.py esté ejecutándose. 2. Reinicia Cursor por completo para actualizar el descubrimiento de herramientas.
• ¿Permiso Denegado?
  • Asegúrate de haber compartido tu hoja de Google con el Correo de la Cuenta de Servicio que se encuentra en tu archivo de credenciales JSON.

---

#VARIABLES DE ENTORNO

SERVICE_FILE_PATH= path to your credentials.json
transport= (sse,stdio,http)
mcp_host= ip to host mcp
mcp_port= port to run mcp server