README.md
Manage appointments, clients, services, and staff via AI-assistant
mcp-altegio
MCP-сервер для Altegio API — управление записями, клиентами, услугами, сотрудниками и расписанием через AI-ассистента.
Возможности
- 18 MCP-инструментов — записи, клиенты, услуги, сотрудники, расписание, финансы
- CRUD-операции — полный цикл создания, чтения, обновления и удаления записей и клиентов
- Умный поиск — автоопределение типа запроса (телефон, email, имя)
- Docker-образ — multi-stage build на Alpine (~184MB), готов к продакшну
- 141 тест — unit, API-клиент, интеграционные MCP-тесты
- Dual transport — stdio (локально) и Streamable HTTP (удалённо, Smithery, облако)
- stdio-транспорт — работает с Claude Desktop, Claude Code, Cursor, VS Code Copilot
Инструменты
18 инструментов, разбитые по категориям:
📅 Записи
| Инструмент | Описание |
|---|---|
get_records |
Записи за период с фильтрами по мастеру/клиенту |
get_records_by_client |
Все записи конкретного клиента |
get_records_by_visit |
Поиск записей по api_id (привязка к внешней системе) |
create_record |
Создать запись с полной настройкой параметров |
book_service |
Быстрое бронирование с привязкой к визиту |
update_record |
Изменить существующую запись |
delete_record |
Удалить запись |
👥 Клиенты
| Инструмент | Описание |
|---|---|
search_clients |
Поиск по имени, телефону или email (авто-определение) |
get_client |
Карточка клиента по ID |
create_client |
Создать нового клиента |
update_client |
Редактировать данные клиента |
🛎️ Услуги и сотрудники
| Инструмент | Описание |
|---|---|
get_services |
Каталог услуг (фильтр по мастеру/категории) |
get_service_categories |
Категории услуг |
get_staff |
Список сотрудников (по умолчанию без уволенных) |
get_staff_member |
Детали конкретного сотрудника |
📊 Расписание и финансы
| Инструмент | Описание |
|---|---|
get_available_times |
Свободные слоты на дату |
get_available_dates |
Рабочие дни мастера |
get_transactions |
Финансовые транзакции за период |
Быстрый старт
Требования
- Bun >= 1.0 или Docker
- Партнёрский и пользовательский токены Altegio API
Установка
Bun (локально)
git clone https://github.com/moro3k/mcp-altegio.git
cd mcp-altegio
bun install
Docker
git clone https://github.com/moro3k/mcp-altegio.git
cd mcp-altegio
docker build -t mcp-altegio .
Конфигурация
| Переменная | Обязательна | Описание |
|---|---|---|
ALTEGIO_TOKEN |
Да | Партнёрский токен API |
ALTEGIO_USER_TOKEN |
Да | Пользовательский токен |
ALTEGIO_COMPANY_ID |
Да | ID компании |
Где взять токены?
- ALTEGIO_TOKEN — партнёрский токен. Получается в кабинете разработчика после регистрации партнёрского аккаунта
- ALTEGIO_USER_TOKEN — пользовательский токен. Получается через авторизацию к API (
POST /auth) с логином и паролем аккаунта Altegio - ALTEGIO_COMPANY_ID — ID компании. Виден в URL панели управления:
app.alteg.io/company/XXXXXX/...
Подключение
Claude Desktop
Добавьте в конфигурацию (~/Library/Application Support/Claude/claude_desktop_config.json на macOS или %APPDATA%\Claude\claude_desktop_config.json на Windows):
Bun
{
"mcpServers": {
"altegio": {
"command": "bun",
"args": ["run", "/полный/путь/к/mcp-altegio/src/index.ts"],
"env": {
"ALTEGIO_TOKEN": "ваш_токен",
"ALTEGIO_USER_TOKEN": "ваш_токен",
"ALTEGIO_COMPANY_ID": "12345"
}
}
}
}
Docker
{
"mcpServers": {
"altegio": {
"command": "docker",
"args": ["run", "-i", "--rm",
"-e", "ALTEGIO_TOKEN",
"-e", "ALTEGIO_USER_TOKEN",
"-e", "ALTEGIO_COMPANY_ID",
"mcp-altegio"],
Tools (5)
get_recordsRetrieve appointments for a specific period with filters for staff or clients.create_recordCreate a new appointment with custom parameters.search_clientsSearch for clients by name, phone number, or email.get_servicesGet a list of available services, optionally filtered by staff or category.get_available_timesCheck available time slots for a specific date.Environment Variables
ALTEGIO_TOKENrequiredPartner API token from Altegio developer cabinetALTEGIO_USER_TOKENrequiredUser API token obtained via authenticationALTEGIO_COMPANY_IDrequiredThe unique ID of the company from the Altegio dashboard URLConfiguration
claude_desktop_config.json
{"mcpServers": {"altegio": {"command": "bun", "args": ["run", "/path/to/mcp-altegio/src/index.ts"], "env": {"ALTEGIO_TOKEN": "your_token", "ALTEGIO_USER_TOKEN": "your_token", "ALTEGIO_COMPANY_ID": "12345"}}}}Try it
→What appointments do I have scheduled for tomorrow?
→Find the client record for John Doe and show his recent visit history.
→Check which staff members are available for a haircut service next Tuesday.
→Book a new appointment for Sarah Smith with the top-rated stylist on Friday at 2 PM.
→Show me the total financial transactions for the last month.