acuity-mcp

Локальный MCP-сервер, предоставляющий API Acuity Scheduling в виде инструментов Claude Code — создание, просмотр, перенос и отмена записей, проверка доступности, список типов записей, календарей и клиентов — всё напрямую из сессии Claude. Поддерживает несколько аккаунтов Acuity одновременно, переключение между ними через аргумент каждого вызова инструмента.

Создан с нуля, потому что поддерживаемого бесплатного MCP для Acuity не существует — единственный найденный в ходе исследования репозиторий на GitHub указывал на npm-пакет, который так и не был опубликован. Использует @modelcontextprotocol/sdk + zod, работает через stdio.

Если вы Claude: прочитайте это в первую очередь

Если пользователь просит вас настроить это, добавить аккаунт Acuity, переключить аккаунты или устранить неполадки с подключением, загрузите .claude/skills/acuity-mcp-setup/SKILL.md из этого репозитория — там есть полная пошаговая инструкция для всего этого. Этот README — справочник для человека; навык — то, чему вы должны следовать на самом деле.

Что нужно перед настройкой

Идентификатор пользователя Acuity Scheduling и API-ключ из Acuity: Business Settings → Integrations → API. Одна пара на каждый аккаунт Acuity, который вы хотите подключить.

⚠️ Acuity ограничивает доступ к API в зависимости тарифного плана. Некоторые планы возвращают 403: API access is only available on Powerhouse plans на каждый запрос — это Acuity отклоняет ваш аккаунт, а не ошибка здесь. Базовая аутентификация проходит успешно (нет 401), но каждый вызов всё равно возвращает 403 — это признак данной ситуации. Если вы столкнулись с этим, либо обновите тарифный план, либо используйте альтернативный путь к тому же аккаунту (например, коннектор Acuity в Zapier, который, как показала практика, не подвержен тому же ограничению).

Установка

npm install

Быстрый старт — один аккаунт

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

Первый добавленный аккаунт автоматически становится основным. Затем зарегистрируйте сервер в Claude Code:

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

Начните новую сессию Claude Code (или выполните /mcp в существующей), чтобы инструменты появились.

Проверьте работоспособность без сессии Claude:

node bin/acuity-accounts.js test

Несколько аккаунтов

Добавьте столько именованных аккаунтов, сколько нужно:

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"

Учётные данные хранятся в ~/.config/acuity-mcp/accounts.json (chmod 600, никогда внутри этого репозитория, никогда не коммитятся). Управляйте ими:

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

Переключение аккаунтов внутри сессии Claude не требует повторной регистрации — каждый инструмент, предоставляемый этим сервером, принимает необязательный аргумент account:

«Список типов записей для тестового аккаунта» → Claude вызывает list_appointment_types с {"account": "sandbox"}.

Попросите Claude выполнить list_accounts в любое время, чтобы увидеть, какие аккаунты настроены и какой из них является основным.

Если вы предпочитаете запускать полностью отдельные регистрации MCP-сервера для каждого аккаунта (например, чтобы каждый отображался как отдельно именованный сервер), это тоже работает — укажите ACUITY_ACCOUNT на имя вместо передачи account в каждом вызове:

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"

Порядок разрешения учётных данных

1. Переменные окружения ACUITY_USER_ID + ACUITY_API_KEY (прямое переопределение, файл аккаунтов не нужен)

2. Аргумент account при вызове инструмента или переменная окружения ACUITY_ACCOUNT — поиск по имени

3. Собственный аккаунт default в accounts.json

4. accounts.json с ровно одним настроенным аккаунтом — используется автоматически

5. Устаревший плоский файл ~/.config/acuity-mcp/credentials (строки ACUITY_USER_ID=.../ACUITY_API_KEY=...) — поддерживается для обратной совместимости со старыми однопользовательскими настройками

Инструменты

Локальные, без вызова API Acuity:

• list_accounts — список настроенных имён/меток аккаунтов и основного аккаунта (никогда API-ключи)

Только чтение:

• list_appointment_types — список доступных для записи типов консультаций

• list_calendars — список календарей/сотрудников

• list_appointments — фильтрация по диапазону дат / календарю / типу / статусу отмены

• get_appointment — полная информация об одной записи по ID

• check_availability_dates — доступные даты в месяце для типа записи

• check_availability_times — доступные временные слоты на дату для типа записи

• list_clients — клиенты, которые записывались на приём

Изменяющие (реальные изменения в живом календаре — Claude запросит подтверждение перед вызовом):

• create_appointment — создать новую запись

• reschedule_appointment — изменить дату/время записи

• cancel_appointment — отменить запись

Все инструменты принимают необязательный аргумент account (см. Несколько аккаунтов).

Не реализовано (та же схема, добавить позже при необходимости): платежи, блоки, формы, вебхуки, подарочные сертификаты.

Извлечённые уроки (прочитайте перед расширением этого сервера)

• 200 OK от изменяющего вызова не доказывает, что изменение произошло. reschedule_appointment изначально вызывал PUT /appointments/:id, который возвращал 200 и повторял неизменённую запись — Acuity молча игнорировал поле datetime на этом эндпоинте. Исправлением стал выделенный маршрут PUT /appointments/:id/reschedule, соответствующий шаблону, который уже использовал cancel_appointment (/appointments/:id/cancel). Всегда повторно запрашивайте данные с помощью get_appointment после записи, прежде чем доверять ей, особенно для любых новых изменяющих инструментов, добавленных позже.

• npx @modelcontextprotocol/inspector --cli ненадёжно передаёт ad-hoc переменные окружения процессу node server.js, который он запускает. Если вы тестируете учётные данные, которые не являются разрешёнными по умолчанию (например, ACUITY_USER_ID=x ACUITY_API_KEY=y npx @modelcontextprotocol/inspector --cli ...), он может молча вернуться к уже настроенным и дать ложноположительный/ложноотрицательный результат. Вместо этого используйте node bin/acuity-accounts.js test <name> — создан специально, чтобы избежать этой ловушки. CLI инспектора остаётся пригодным для своей первоначальной цели: тестирования разрешённых учётных данных по умолчанию или --method tools/list для проверки схем инструментов.

Ручная проверка

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