acuity-mcp

Un servidor MCP local que expone la API de Acuity Scheduling como herramientas de Claude Code: listar, crear, reprogramar, cancelar citas, verificar disponibilidad, listar tipos de cita, calendarios y clientes, todo directamente desde una sesión de Claude. Soporta múltiples cuentas de Acuity en paralelo, seleccionables por llamada a herramienta.

Creado a medida porque no existe un MCP gratuito mantenido para Acuity — el único repositorio de GitHub encontrado durante la investigación apuntaba a un paquete npm que nunca se publicó. Usa @modelcontextprotocol/sdk + zod, se ejecuta sobre stdio.

Si eres Claude: lee esto primero

Si un usuario te pide configurar esto, añadir una cuenta de Acuity, cambiar de cuenta o solucionar un problema de conexión, carga .claude/skills/acuity-mcp-setup/SKILL.md en este repositorio — tiene la guía completa paso a paso para todo eso. Este README es la referencia para humanos; la habilidad es lo que deberías seguir realmente.

Lo que necesitas antes de la configuración

Un ID de usuario de Acuity Scheduling y una Clave de API, desde Acuity: Configuración del negocio → Integraciones → API. Un par por cada cuenta de Acuity que quieras conectar.

⚠️ Acuity restringe el acceso a la API según el plan contratado. Algunos planes devuelven 403: API access is only available on Powerhouse plans en cada solicitud — esto es Acuity rechazando tu cuenta, no un error aquí. Si la Autenticación Básica funciona (sin 401) pero todas las llamadas siguen dando 403, esa es la señal. Si te ocurre, actualiza el plan o usa una vía alternativa para la misma cuenta (por ejemplo, un conector de Acuity para Zapier, que empíricamente no ha estado sujeto a la misma restricción).

Instalación

npm install

Inicio rápido — una cuenta

node bin/acuity-accounts.js add production --user-id <your-user-id> --api-key <your-api-key>

La primera cuenta que añadas se convierte automáticamente en la predeterminada. Luego registra el servidor con Claude Code:

claude mcp add acuity -s user -- node "$(pwd)/server.js"

Inicia una nueva sesión de Claude Code (o ejecuta /mcp en una existente) para que las herramientas aparezcan.

Verifica que funciona sin una sesión de Claude:

node bin/acuity-accounts.js test

Múltiples cuentas

Añade tantas cuentas con nombre como quieras:

node bin/acuity-accounts.js add production --user-id 1111111 --api-key aaaa... --label "Real account"
node bin/acuity-accounts.js add sandbox    --user-id 2222222 --api-key bbbb... --label "Trial/test account"

Las credenciales residen en ~/.config/acuity-mcp/accounts.json (chmod 600, nunca dentro de este repositorio, nunca se confirman). Gestiona con:

node bin/acuity-accounts.js list                # see configured accounts (never prints API keys)
node bin/acuity-accounts.js set-default sandbox # change which one is used by default
node bin/acuity-accounts.js remove sandbox      # remove one
node bin/acuity-accounts.js test sandbox        # verify one specific account's credentials

Cambiar de cuenta dentro de una sesión de Claude no requiere volver a registrar nada — cada herramienta que expone este servidor acepta un argumento account opcional:

"Lista los tipos de cita para la cuenta sandbox" → Claude llama a list_appointment_types con {"account": "sandbox"}.

Pide a Claude que ejecute list_accounts en cualquier momento para ver qué está configurado y cuál es la cuenta predeterminada.

Si prefieres ejecutar registros de servidor MCP completamente separados por cuenta (por ejemplo, para que cada uno aparezca como un servidor con nombre distinto), también funciona — apunta ACUITY_ACCOUNT a un nombre en lugar de pasar account en cada llamada:

claude mcp add acuity-production -s user -e ACUITY_ACCOUNT=production -- node "$(pwd)/server.js"
claude mcp add acuity-sandbox    -s user -e ACUITY_ACCOUNT=sandbox    -- node "$(pwd)/server.js"

Orden de resolución de credenciales

1. Variables de entorno ACUITY_USER_ID + ACUITY_API_KEY (anulación directa, no necesita archivo de cuentas)

2. Argumento account en una llamada a herramienta, o la variable de entorno ACUITY_ACCOUNT — se busca por nombre

3. Cuenta default propia de accounts.json

4. accounts.json con exactamente una cuenta configurada — se usa automáticamente

5. Archivo de credenciales plano heredado ~/.config/acuity-mcp/credentials (líneas ACUITY_USER_ID=.../ACUITY_API_KEY=... ) — compatible con versiones anteriores para configuraciones antiguas de una sola cuenta

Herramientas

Solo local, sin llamada a la API de Acuity:

• list_accounts — lista los nombres/etiquetas de cuentas configuradas y la predeterminada (nunca las claves de API)

Solo lectura:

• list_appointment_types — lista los tipos de consulta reservables

• list_calendars — lista calendarios/personal

• list_appointments — filtrable por rango de fechas / calendario / tipo / estado de cancelación

• get_appointment — detalle completo de una cita por ID

• check_availability_dates — fechas disponibles en un mes para un tipo de cita

• check_availability_times — franjas horarias disponibles en una fecha para un tipo de cita

• list_clients — clientes que han reservado citas

Mutación (cambios reales en el calendario activo — Claude pedirá confirmación antes de llamar a estas):

• create_appointment — reservar una nueva cita

• reschedule_appointment — cambiar la fecha/hora de una cita

• cancel_appointment — cancelar una cita

Todas las herramientas aceptan un argumento account opcional (ver Múltiples cuentas).

No implementado (mismo patrón, añadir después si es necesario): pagos, bloqueos, formularios, webhooks, certificados de regalo.

Lecciones aprendidas (lee antes de extender este servidor)

• Un 200 OK de una llamada de mutación no prueba que la mutación ocurriera. reschedule_appointment originalmente llamaba a PUT /appointments/:id, que devolvía 200 y repetía la cita sin cambios — Acuity ignoraba silenciosamente el campo datetime en ese endpoint. La corrección fue la ruta dedicada PUT /appointments/:id/reschedule, siguiendo el patrón que cancel_appointment ya usaba (/appointments/:id/cancel). Siempre vuelve a obtener con get_appointment después de una escritura antes de confiar en ella, especialmente para cualquier nueva herramienta de mutación que se añada después.

• npx @modelcontextprotocol/inspector --cli no reenvía de forma fiable las variables de entorno ad-hoc al proceso node server.js que genera. Si estás probando credenciales que no son la predeterminada resuelta (por ejemplo, ACUITY_USER_ID=x ACUITY_API_KEY=y npx @modelcontextprotocol/inspector --cli ...), puede caer silenciosamente en lo que ya esté configurado y dar un falso positivo/negativo. Usa node bin/acuity-accounts.js test <nombre> en su lugar — creado específicamente para evitar esta trampa. El CLI del inspector sigue siendo útil para su propósito original: probar las credenciales predeterminadas resueltas, o --method tools/list para verificar los esquemas de las herramientas.

Verificación manual

node bin/acuity-accounts.js test            # tests the default/env-resolved account
node bin/acuity-accounts.js test <name>     # tests one specific named account
npx @modelcontextprotocol/inspector --cli node server.js --method tools/list   # confirms the server starts and tools register correctly