DanielBayon/mcp-sheets-server

MCP Server para Google Sheets - Railway

📋 Descripción

Este es un servidor MCP (Model Context Protocol) que permite a ChatGPT leer y escribir en una tabla de Google Sheets. Perfecto para que ChatGPT pueda guardar investigaciones, consultar datos existentes y mantener un registro persistente de información.

🚀 Características

• 🔍 Búsqueda: Busca investigaciones en Google Sheets
• 📖 Lectura: Recupera documentos completos por ID
• ✍️ Escritura: Guarda nuevas investigaciones (con confirmación en ChatGPT)
• 🔧 Auto-configuración: Crea automáticamente las columnas necesarias
• 🌐 Remoto: Desplegable en Replit, Railway, Docker, etc.

📊 Estructura de Datos

El servidor maneja una tabla con estas columnas:

🛠️ Instalación y Configuración

1. Configurar Google Cloud

1. Ve a Google Cloud Console
2. Crea un nuevo proyecto o selecciona uno existente
3. Habilita estas APIs:
   • Google Sheets API
   • Google Drive API
4. Crea una Service Account:
   • Ve a "IAM & Admin" > "Service Accounts"
   • Crea una nueva Service Account
   • Descarga el JSON de credenciales

2. Configurar Google Sheet

1. Crea un Google Sheet nuevo o usa uno existente
2. Comparte el Sheet con el email de la Service Account (permisos de Editor)
3. Copia el ID del Sheet desde la URL: https://docs.google.com/spreadsheets/d/{SHEET_ID}/edit

3. Configurar Variables de Entorno

Copia .env.example a .env y completa:

# ID del Google Sheet
SHEET_ID=1AbCdEfGhIjKlMnOpQrStUvWxYz123456789

# Nombre de la pestaña (opcional, por defecto "data")
SHEET_NAME=data

# JSON de la Service Account (en una sola línea)
GOOGLE_SERVICE_ACCOUNT_JSON={"type":"service_account","project_id":"..."}

# Máximo resultados en búsquedas (opcional)
MAX_RESULTS=20

4. Instalar Dependencias

pip install -r requirements.txt

5. Ejecutar el Servidor

python server.py

El servidor estará disponible en: http://localhost:8000 El endpoint MCP (SSE) estará en: http://localhost:8000/sse/

🌐 Despliegue

Opción 1: Replit

1. Crea un Repl de Python
2. Sube los archivos server.py y requirements.txt
3. En Secrets (o .env), añade las variables de entorno
4. Ejecuta el proyecto
5. URL del MCP: https://<tu-repl>.replit.dev/sse/

Opción 2: Railway

1. Conecta tu repositorio a Railway
2. Configura las variables de entorno en el dashboard
3. Railway detectará automáticamente el requirements.txt
4. URL del MCP: https://<tu-app>.railway.app/sse/

Opción 3: Docker

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY server.py .
COPY .env .

EXPOSE 8000
CMD ["python", "server.py"]

🤖 Conexión con ChatGPT

1. Developer Mode

1. Ve a ChatGPT Settings → Connectors → Advanced
2. Activa "Developer mode (beta)"

2. Importar MCP Server

1. Click en "Import MCP server"
2. Configura:
   • Label: sheets
   • URL: https://tu-servidor.com/sse/
   • Allowed tools: search, fetch, save_investigation
   • Require approval: never (o como prefieras)

3. Usar desde ChatGPT

• Deep Research: Activa "Use Connectors" al crear una investigación
• Chat normal: Menciona que quieres usar el conector de sheets

🔧 Herramientas MCP

search

Busca investigaciones en la tabla.

Parámetros:

• query (string): Texto a buscar

Respuesta:

{
  "results": [
    {"id": "uuid-123", "title": "Título", "url": "https://..."}
  ]
}

fetch

Recupera una investigación completa por ID.

Parámetros:

• id (string): ID único de la fila

Respuesta:

{
  "id": "uuid-123",
  "title": "Título",
  "text": "Resumen: ... \n\nNotas: ...",
  "url": "https://...",
  "metadata": {"timestamp": "...", "tags": "...", ...}
}

save_investigation

Guarda una nueva investigación (requiere confirmación en ChatGPT).

Parámetros:

• titulo (string): Título
• resumen (string): Resumen
• url (string): URL relacionada
• notas (string): Notas adicionales
• tags (array): Lista de etiquetas
• confianza (string): Nivel de confianza
• solicitado_por (string): Solicitante
• fuente (string): Fuente

Respuesta:

{
  "ok": true,
  "inserted": {"id": "uuid-123", "timestamp": "...", ...}
}

🔒 Seguridad

• Principio de mínimo privilegio: La Service Account solo accede al Sheet específico
• Write actions: ChatGPT pide confirmación manual antes de escribir
• Auditoría: Todas las escrituras quedan registradas con timestamp y usuario
• Validación: Los campos se validan antes de guardar

🚨 Solución de Problemas

Error: "SHEET_ID no configurado"

• Verifica que la variable SHEET_ID esté configurada correctamente

Error: "Permission denied"

• Asegúrate de haber compartido el Sheet con el email de la Service Account
• Verifica que los permisos sean de "Editor"

Error: "API not enabled"

• Habilita Google Sheets API y Google Drive API en Google Cloud Console

ChatGPT no encuentra el servidor

• Verifica que la URL termine en /sse/
• Asegúrate de que el servidor esté ejecutándose y sea accesible públicamente

📝 Ejemplos de Uso

Buscar investigaciones sobre IA

ChatGPT usará: search("inteligencia artificial 2025")

Guardar una nueva investigación

ChatGPT usará: save_investigation(
  titulo="Estado del mercado de IA 2025",
  resumen="Tendencias: agentes, RAG híbrido, edge.",
  url="https://ejemplo.com/informe",
  tags=["IA", "mercado", "tendencias"],
  confianza="alta",
  solicitado_por="Daniel",
  fuente="web research"
)

🔄 Actualizaciones Futuras

• Búsqueda semántica con embeddings
• Filtros avanzados por fechas, tags, confianza
• Soporte para múltiples Sheets
• Dashboard web para visualización
• Exportación a diferentes formatos

📄 Licencia

MIT License - Úsalo libremente para tus proyectos.

¿Necesitas ayuda? Abre un issue o consulta la documentación de FastMCP y gspread.