apps-script-mcp-server

Un servidor MCP que permite a Claude leer y enviar código de Google Apps Script (.gs, .html, appsscript.json) directamente a un proyecto de script — sin necesidad de copiar y pegar código manualmente en el editor de Apps Script.

Construido para el sistema de vigilancia de enfermedades de Kwara (panel KWARAB), pero funciona con cualquier proyecto de Apps Script al que tengas acceso de edición.

Lo que puede hacer

Limitación importante que debes conocer de antemano: al enviar código con apps_script_update_file / apps_script_update_content se actualiza el proyecto editable, igual que si escribieras en el editor de scripts y guardaras. No actualiza automáticamente nada que ya esté desplegado (por ejemplo, una URL de aplicación web en vivo o activadores vinculados a una versión desplegada específica). Para publicar los cambios, crea una versión (apps_script_create_version) y luego vuelve a desplegar desde el editor de Apps Script — este servidor no toca la publicación de despliegues, a propósito, ya que es una acción más delicada que vale la pena hacer manualmente las primeras veces.

1. Configuración única de Google Cloud (haz esto primero)

Necesitas un proyecto de Google Cloud con la API de Apps Script habilitada y un cliente OAuth. Esto toma unos 5 minutos.

1. Crear o elegir un proyecto de Google Cloud Ve a https://console.cloud.google.com/projectcreate y crea un proyecto (cualquier nombre está bien — p. ej., "kwarab-apps-script-mcp"). Si ya tienes un proyecto de GCP que usas para otros trabajos de Kwara/Ekiti, puedes reutilizarlo.

2. Habilitar la API de Apps Script en el proyecto Ve a https://console.cloud.google.com/apis/library/script.googleapis.com, selecciona tu proyecto y haz clic en Habilitar.

3. Configurar la pantalla de consentimiento OAuth Ve a https://console.cloud.google.com/apis/credentials/consent

   • Tipo de usuario: Externo (a menos que tengas una organización de Google Workspace, en cuyo caso Interno está bien)

   • Completa el nombre de la aplicación (p. ej., "Apps Script MCP"), tu correo electrónico como contacto de soporte

   • Ámbitos: puedes omitir la adición de ámbitos aquí — el servidor los solicita directamente

   • Usuarios de prueba: agrega tu propia dirección de correo electrónico de Google (necesario mientras la aplicación esté en estado "Prueba", que es adecuado para uso personal/interno)

4. Crear un cliente OAuth Ve a https://console.cloud.google.com/apis/credentials

   • Haz clic en Crear credenciales → ID de cliente OAuth

   • Tipo de aplicación: Aplicación de escritorio

   • Nómbralo como quieras (p. ej., "Apps Script MCP Desktop")

   • Haz clic en Crear, luego en Descargar JSON

5. Guarda el archivo descargado como credentials.json en la carpeta raíz de este proyecto (la misma carpeta de este README). No confirmes ni compartas este archivo: identifica tu cliente OAuth (no tu cuenta personal, pero aun así manténlo privado).

6. Habilitar la API de Apps Script para tu propia cuenta de Google Esto es independiente del paso 2 (ese habilita la API para el proyecto; este la habilita para la cuenta de Google que posee/edita el script). Ve a https://script.google.com/home/usersettings y activa "API de Google Apps Script".

2. Instalar y autorizar

npm install
npm run build
npm run authorize

npm run authorize abre tu navegador, te pide que inicies sesión con la cuenta de Google que tiene acceso al proyecto de Apps Script de vigilancia de enfermedades de Kwara, y te solicita que apruebes el acceso. Después de aprobar, guarda un token de actualización en token.json en esta carpeta — solo necesitas hacer esto una vez (vuelve a ejecutarlo si alguna vez revocas el acceso o cambias de cuenta de Google).

Si no se abre nada automáticamente: la terminal mostrará una URL — cópiala y pégala en cualquier navegador, aprueba, y serás redirigido de vuelta a localhost donde el script está escuchando; la terminal confirmará el éxito.

3. Conectarlo a Claude

Opción A: Local (stdio) — Claude Code / Claude Desktop

Agrega a tu configuración de MCP (p. ej., claude_desktop_config.json o tu configuración de MCP de Claude Code):

{
  "mcpServers": {
    "apps-script": {
      "command": "node",
      "args": ["/absolute/path/to/apps-script-mcp-server/dist/index.js"]
    }
  }
}

Reinicia Claude Desktop / Claude Code después de agregar esto. Deberías ver apps-script listado entre los servidores MCP conectados, con herramientas como apps_script_update_file disponibles.

Opción B: Remoto (HTTP), p. ej., alojado en Render

El servidor también funciona como un servicio HTTP independiente — configura TRANSPORT=http. Esto es lo que render.yaml en este repositorio configura automáticamente. Consulta Despliegue en Render más abajo.

Un servidor remoto es accesible para cualquiera que tenga su URL, por lo que cada solicitud a /mcp debe incluir un token de portador que coincida con la variable de entorno MCP_SERVER_TOKEN que hayas establecido:

Authorization: Bearer <your MCP_SERVER_TOKEN value>

En la configuración del conector MCP remoto de Claude, agrega la URL del servidor (https://<tu-servicio>.onrender.com/mcp) y configura ese encabezado. /healthz está intencionalmente sin autenticación para que las comprobaciones de salud de Render puedan alcanzarlo.

Despliegue en Render

Este repositorio incluye un render.yaml Blueprint, por lo que Render puede crear el servicio con la mayoría de los ajustes predefinidos.

1. En el panel de Render: Nuevo → Blueprint, conecta tu cuenta de GitHub si aún no lo has hecho, y selecciona este repositorio. Render leerá render.yaml.

2. Render te pedirá las variables de entorno marcadas con sync: false:

   • MCP_SERVER_TOKEN — inventa una cadena aleatoria larga (p. ej., openssl rand -hex 32). Esta es la que Claude debe enviar como token de portador.

   • GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET, GOOGLE_OAUTH_REFRESH_TOKEN — genera estas localmente primero (pasos 1–2 anteriores, incluido npm run authorize), luego abre el token.json resultante y copia client_id, client_secret y refresh_token en los campos de variable de entorno de Render. Render nunca recibe un navegador, por lo que esta ruta de credenciales sin cabeza reemplaza el paso local de npm run authorize.

3. Despliega. Una vez activo, el endpoint MCP es https://<tu-servicio>.onrender.com/mcp.

4. En el plan gratuito, Render apaga el servicio después de la inactividad — la primera solicitud después de la inactividad será lenta (arranque en frío) mientras se reactiva.

4. Usarlo

Necesitarás el ID de script del proyecto de Apps Script de vigilancia de enfermedades de Kwara. Encuéntralo abriendo el proyecto en https://script.google.com y copiando el ID de la URL:

https://script.google.com/home/projects/<THIS_IS_THE_SCRIPT_ID>/edit

(Si el Apps Script está vinculado a la Hoja de Cálculo de Google de KWARAB en lugar de ser independiente, abre la hoja → Extensiones → Apps Script para llegar al mismo editor y URL).

Luego, en una conversación de Claude con este servidor MCP conectado, puedes decir cosas como:

• "Muéstrame el Code.gs actual en el script <scriptId>"

• "Actualiza la función sendAlertEmail en Code.gs para que también incluya en copia al supervisor de DSNO"

• "Sube este nuevo archivo Utils.gs con estas funciones auxiliares: ..."

• "Crea una nueva versión llamada 'Añadir lógica de autocomposición de EPID AFP'"

Notas de seguridad

• credentials.json y token.json ambos otorgan acceso a proyectos de Apps Script que puedas editar. Mantenlos fuera del control de versiones (se incluye un .gitignore) y no los compartas.

• Los ámbitos OAuth solicitados (script.projects, script.deployments) no incluyen acceso a Gmail, Hojas de Cálculo o Drive más allá de lo necesario para leer/escribir contenido del proyecto de script e inspeccionar despliegues.

• Para revocar el acceso en cualquier momento: https://myaccount.google.com/permissions → busca el nombre del cliente OAuth que configuraste en el paso 4 anterior → Eliminar acceso. Elimina token.json después.

Solución de problemas