MCP Google Apps Script Server

Servidor MCP Google Apps Script

🎯 ¿Por qué MCP GAS Server?

El Problema

Google Apps Script es potente para automatizar Google Workspace, pero desarrollar proyectos de GAS tradicionalmente requiere:

• Cambiar entre el desarrollo local y el editor en línea
• Copiar y pegar código manualmente
• Sin un sistema de módulos adecuado ni control de versiones
• Herramientas limitadas para pruebas e implementación

La Solución

MCP GAS Server conecta asistentes de IA con Google Apps Script, permitiendo:

• Desarrollo Impulsado por IA: Dile a Claude/Cursor qué construir y él se encarga de la implementación
• Módulos CommonJS Completos: require(), module.exports, resolución automática de dependencias - escribe GAS como Node.js
• Ejecución Ad-hoc: Ejecuta cualquier expresión de JavaScript al instante - sin implementación, sin funciones envolventes necesarias
• Canal de Implementación de Producción: Flujo de trabajo dev → staging → prod con control de versiones, promoción y reversión
• Interfaz Inspirada en Unix: Comandos familiares (cat, grep, ls, find, sed) para una gestión intuitiva de proyectos GAS
• Desarrollo Local: Escribe código localmente con soporte completo de IDE
• Sincronización Automática: Sincronización bidireccional entre archivos locales y la nube de Google
• Integración con Git: Control de versiones para tus proyectos GAS con fusión segura

¿Para Quién Es Esto?

• Desarrolladores que quieren que la IA maneje el código repetitivo de Google Apps Script
• Equipos que automatizan flujos de trabajo de Google Workspace
• No programadores que necesitan funciones personalizadas de Google Sheets o automatización
• Cualquiera cansado de las limitaciones del editor de scripts en línea de Google

💡 Casos de Uso

Lo Que Puedes Construir

• 📊 Funciones Personalizadas de Hojas de Cálculo: Cálculos complejos, procesamiento de datos, integraciones de API
• 📧 Automatización de Correos Electrónicos: Procesa Gmail, envía correos masivos, gestiona borradores
• 📅 Gestión de Calendario: Programa eventos, sincroniza calendarios, automatiza la creación de reuniones
• 🗂️ Automatización de Drive: Organización de archivos, sistemas de respaldo, generación de documentos
• 📝 Procesamiento de Documentos: Genera informes, fusiona documentos, extrae datos
• 🔗 Integraciones de API: Conecta Google Workspace con servicios externos
• 🤖 Chatbots y Complementos: Construye herramientas personalizadas para Sheets, Docs y Forms

Ejemplos Reales

// Tell your AI: "Create a function that fetches stock prices and updates my spreadsheet"
// AI will create, deploy, and test the entire solution

// Tell your AI: "Build an expense tracker that categorizes Gmail receipts"
// AI handles OAuth, Gmail API, and spreadsheet integration

// Tell your AI: "Make a custom menu in Sheets for data analysis tools"
// AI creates the UI, functions, and deploys everything

🚀 Inicio Rápido

⚡ Instalación en 30 Segundos

curl -fsSL https://raw.githubusercontent.com/whichguy/mcp_gas/main/install.sh | bash -s -- --auto

git clone https://github.com/whichguy/mcp_gas.git && cd mcp_gas && ./install.sh

Requisitos Previos

🎯 Primer Proyecto en 2 Minutos

curl -fsSL https://raw.githubusercontent.com/whichguy/mcp_gas/main/install.sh | bash

⚙️ Detalles de Instalación

Lo Que Hace el Instalador

El script install.sh maneja todo automáticamente:

1. 🔄 Descarga el Repositorio (si se usa curl)
2. 📦 Instala Dependencias (npm install)
3. 🔨 Compila el Proyecto (npm run build)
4. 🔍 Detecta Tus IDEs (verifica más de 10 IDEs)
5. ⚙️ Configura Cada IDE (actualiza la configuración de MCP)
6. 🔗 Vincula a dist/src/index.js (compilación de producción)

Características:

• ✅ Idempotente - Seguro de ejecutar varias veces
• 💾 Crea Copias de Seguridad - Antes de cualquier modificación
• 🔐 Verifica OAuth - Te guía a través de la configuración de Google

Opciones de Línea de Comandos

./install.sh --dry-run       # Preview changes without making them
./install.sh --interactive   # Choose which IDEs to configure
./install.sh --auto          # Non-interactive mode (for CI/CD)
./install.sh --force         # Update existing configurations
./install.sh --help          # Show detailed usage

Compilación Manual (Avanzado)

Si el instalador falla o necesitas una configuración personalizada:

# 1. Clone repository
git clone https://github.com/whichguy/mcp_gas.git
cd mcp_gas

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Configure your IDE manually
# Point to: /absolute/path/to/mcp_gas/dist/src/index.js

Nota: El binario del servidor está en dist/src/index.js después de compilar, no en el directorio fuente.

Desinstalación

# Remove MCP GAS from all IDEs
./uninstall.sh

# With cleanup options:
./uninstall.sh --cleanup-build      # Also remove dist/ and node_modules/
./uninstall.sh --cleanup-backups    # Remove all backup files
./uninstall.sh --dry-run           # Preview what would be removed

📋 Configuración de Google Cloud

Configuración Única

1. Habilita la API de Google Apps Script:

   • Visita Consola de Google Cloud
   • Crea o selecciona un proyecto
   • Busca "Google Apps Script API" y habilítala

2. Crea Credenciales OAuth 2.0:

   • Navega a APIs y Servicios → Credenciales
   • Haz clic en "Crear Credenciales" → "ID de cliente OAuth"
   • Tipo de aplicación: Aplicación de escritorio
   • Descarga el JSON y guárdalo como oauth-config.json en la raíz del proyecto

🖥️ IDEs Compatibles

El Servidor MCP GAS funciona con cualquier cliente compatible con MCP:

{
  "mcpServers": {
    "gas": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_gas/dist/src/index.js"],
      "env": {"NODE_ENV": "production"}
    }
  }
}

{
  "mcpServers": {
    "gas": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_gas/dist/src/index.js"],
      "env": {"NODE_ENV": "production"}
    }
  }
}

{
  "context_servers": {
    "gas": {
      "command": {
        "path": "node",
        "args": ["/absolute/path/to/mcp_gas/dist/src/index.js"]
      }
    }
  }
}

[mcp_servers.gas]
command = "node"
args = ["/absolute/path/to/mcp_gas/dist/src/index.js"]

[[mcp_servers.gas.env]]
NODE_ENV = "production"

📦 Lo Que Está Incluido

🛠️ 50 Herramientas Especializadas

Herramientas Inteligentes vs. Crudas

• Herramientas inteligentes (cat, write): Manejan automáticamente el envoltorio de módulos CommonJS
• Herramientas crudas (raw_cat, raw_write): Preservan el contenido exacto del archivo
• Elige según quieras gestión automática de módulos o control total

🎓 Cuándo Usar MCP GAS Server

✅ Perfecto Para

• Proyectos de Automatización: Automatización de Gmail, Calendar, Drive, Sheets
• Funciones Personalizadas: Fórmulas complejas de hojas de cálculo y procesamiento de datos
• Integraciones de API: Conectar Google Workspace con servicios externos
• Prototipado Rápido: Pruebas de concepto rápidas y MVP
• Aprender GAS: Deja que la IA enseñe con el ejemplo

❌ No Ideal Para

• Aplicaciones Grandes: Considera App Engine o Cloud Functions para aplicaciones complejas
• Sistemas en Tiempo Real: GAS tiene límites de tiempo de ejecución (6 minutos)
• Computación Pesada: CPU/memoria limitados en comparación con servidores dedicados
• Datos Sensibles: Evalúa los requisitos de seguridad cuidadosamente

🛠️ Características Avanzadas

Integración con Flujo de Trabajo Git

// Set up .git/config breadcrumb file first
mcp__gas__write({
  scriptId: "...",
  path: ".git/config",
  content: JSON.stringify({ repository: "https://github.com/...", localPath: "~/my-project" })
})

// Stateless sync: preview then apply
mcp__gas__rsync({ operation: "pull", scriptId: "...", dryrun: true })
mcp__gas__rsync({ operation: "pull", scriptId: "..." })

// Standard git workflow works in sync folder
cd ~/gas-repos/project-xxx
git add . && git commit -m "Update" && git push

Sistema de Módulos

// Write modular code with CommonJS
const utils = require('./utils');
const api = require('./api/client');

function processData() {
  const data = api.fetchData();
  return utils.transform(data);
}

module.exports = { processData };

Ejemplo de Primer Proyecto

// Tell your AI assistant:
"Create a Google Apps Script project that calculates Fibonacci numbers"

// The AI will execute:
// 1. Authenticate
await mcp__gas__auth({ mode: "start" });

// 2. Create project
const project = await mcp__gas__project_create({ 
  title: "Fibonacci Calculator" 
});

// 3. Add code
await mcp__gas__write({
  scriptId: project.scriptId,
  path: "fibonacci",
  content: `
    function fibonacci(n) {
      if (n <= 1) return n;
      return fibonacci(n - 1) + fibonacci(n - 2);
    }
    
    function test() {
      Logger.log(fibonacci(10)); // 55
    }
    
    module.exports = { fibonacci };
  `
});

// 4. Execute
const result = await mcp__gas__run({
  scriptId: project.scriptId,
  js_statement: "require('fibonacci').fibonacci(10)"
});
// Returns: 55

📚 Referencia Rápida de Comandos

Operaciones del Sistema de Archivos (inspirado en Unix)

// Read file contents (auto-unwraps CommonJS)
mcp__gas__cat({ scriptId: "...", path: "utils/helper" })

// List files matching pattern
mcp__gas__ls({ scriptId: "...", path: "utils/*" })

// ⚡ RECOMMENDED: High-performance multi-pattern search with ripgrep
mcp__gas__ripgrep({
  scriptId: "...",
  pattern: "function.*test",
  ignoreCase: true,
  context: 2
})

// Simple grep (use ripgrep for advanced searches)
mcp__gas__grep({ scriptId: "...", pattern: "function.*test", outputMode: "content" })

// Find files by name pattern
mcp__gas__find({ scriptId: "...", name: "*.test" })

// Find/replace with regex
mcp__gas__sed({
  scriptId: "...",
  pattern: "console\\.log",
  replacement: "Logger.log"
})

// ⚡ Advanced ripgrep features (STRONGLY RECOMMENDED over grep)
mcp__gas__ripgrep({
  scriptId: "...",
  pattern: "TODO|FIXME|HACK",  // Multi-pattern OR search
  ignoreCase: true,             // Case-insensitive
  sort: "path",                 // Alphabetical sorting
  trim: true,                   // Clean whitespace
  context: 2,                   // Show 2 lines of context
  showStats: true               // Performance statistics
})

Ejecución de Código Ad-hoc

// Execute mathematical expressions
mcp__gas__run({ scriptId: "...", js_statement: "Math.PI * 2" })

// Call Google Apps Script services
mcp__gas__run({
  scriptId: "...",
  js_statement: "DriveApp.getRootFolder().getName()"
})

// Execute project functions with CommonJS
mcp__gas__run({
  scriptId: "...",
  js_statement: "require('Calculator').fibonacci(10)"
})

// Complex data operations
mcp__gas__run({
  scriptId: "...",
  js_statement: `
    const data = require('API').fetchData();
    const sheet = SpreadsheetApp.create('Report');
    sheet.getActiveSheet().getRange(1,1,data.length,3).setValues(data);
    return sheet.getId();
  `
})

Desarrollo de Módulos CommonJS

// Write module with automatic CommonJS wrapping
mcp__gas__write({
  scriptId: "...",
  path: "Calculator",
  content: `
    function add(a, b) { return a + b; }
    function multiply(a, b) { return a * b; }
    module.exports = { add, multiply };
  `
})

// Use require() in other modules - automatic dependency resolution
mcp__gas__write({
  scriptId: "...",
  path: "Main",
  content: `
    const calc = require('Calculator');
    const result = calc.add(5, calc.multiply(2, 3));
    Logger.log(result);  // Logs: 11
  `
})

// Read shows clean user code (CommonJS wrapper removed)
mcp__gas__cat({ scriptId: "...", path: "Calculator" })
// Returns user code without _main() wrapper

Integración con Git

// Create .git/config breadcrumb file
mcp__gas__write({
  scriptId: "...",
  path: ".git/config",
  content: JSON.stringify({
    repository: "https://github.com/owner/repo.git",
    localPath: "~/my-projects/gas-app"
  })
})

// Stateless sync: preview then apply
mcp__gas__rsync({ operation: "pull", scriptId: "...", dryrun: true })
mcp__gas__rsync({ operation: "pull", scriptId: "..." })

// Manage sync folder configuration
mcp__gas__config({
  operation: "set",
  setting: "sync_folder",
  scriptId: "...",
  value: "~/my-projects/gas-app"
})

🔧 Solución de Problemas

Problemas Comunes

Modo de Depuración

# Enable debug logging
DEBUG=mcp:* npm start

# Test installation without changes
./install.sh --dry-run

# Check configuration
cat ~/.claude/claude_desktop_config.json | jq '.mcpServers.gas'

📂 Estructura del Proyecto

mcp_gas/
├── src/                     # TypeScript source code
│   ├── tools/              # ~50 MCP tools
│   ├── auth/               # OAuth authentication
│   ├── api/                # Google Apps Script API client
│   └── server/             # MCP server implementation
├── dist/                    # Compiled JavaScript (after build)
├── test/                    # Test suites
├── docs/                    # Documentation
├── install.sh              # Automated installer
├── uninstall.sh            # Clean uninstaller
├── gas-config.json         # Project configuration
└── oauth-config.json       # OAuth credentials (create this)

🧪 Desarrollo

Configuración

# Clone and install
git clone https://github.com/whichguy/mcp_gas.git
cd mcp_gas
npm install

# Development mode with watch
npm run dev

# Build for production
npm run build

Pruebas

npm test                    # Run all tests
npm run test:unit          # Unit tests only
npm run test:integration   # Integration tests (requires auth)
npm run test:system        # System-level tests
npm run test:security      # Security validation

Arquitectura

El Servidor MCP GAS usa una arquitectura en capas:

1. Capa de Protocolo MCP: Maneja la comunicación con los asistentes de IA
2. Capa de Herramientas: ~50 herramientas especializadas para operaciones de GAS
3. Capa de Autenticación: Flujo OAuth 2.0 PKCE con gestión de tokens
4. Capa de Cliente API: Cliente de Google Apps Script API v1 con limitación de velocidad
5. Capa del Sistema de Archivos: Caché local y sincronización

📚 Documentación

Referencia Completa de Herramientas

• docs/REFERENCE.md - Referencia completa de las 63 herramientas con capacidades, limitaciones y matriz de compatibilidad

Guías para Desarrolladores

• docs/CROSS_TOOL_REFERENCES.md - Estrategia para referencias entre herramientas y encadenamiento de flujos de trabajo
• docs/SCHEMA_ENHANCEMENTS_SUMMARY.md - Seguimiento del progreso para mejoras de esquema
• Guía de Arquitectura - Diseño del sistema e internos
• Integración con Git - Flujos de trabajo de control de versiones
• Documentación de API - Referencia de API de TypeScript
• Ejemplos - Proyectos de muestra y casos de uso

Esquemas de Herramientas Mejorados

Todas las herramientas ahora incluyen:

• Compatibilidad de Tipo de Script - Indicación clara de soporte independiente vs. vinculado a contenedor
• Limitaciones - Restricciones específicas, cuotas y limitaciones de API
• Referencias entre Herramientas - Requisitos previos, próximos pasos, alternativas y guía de recuperación de errores
• ⚡ Preferencia de Herramienta de Búsqueda - Se RECOMIENDA ENCARECIDAMENTE ripgrep sobre grep para todas las búsquedas (multi-patrón, mayúsculas inteligentes, control de contexto, mejor rendimiento)

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Consulta CONTRIBUTING.md para las pautas.

• 🐛 Reportar errores
• 💡 Solicitar características
• 📖 Mejorar la documentación
• 🔧 Enviar pull requests

📄 Licencia

MIT - Consulte LICENSE para obtener detalles.

🙏 Agradecimientos

Construido sobre:

• Model Context Protocol por Anthropic
• Google Apps Script API
• TypeScript, Node.js y la increíble comunidad de código abierto

🌟 ¿Listo para potenciar tu desarrollo de Google Apps Script?

     

Hecho con ❤️ por la comunidad MCP GAS