retensy-mcp
MCP-сервер (+ скилл для Claude Code) для сборки и публикации воронок/автоматизаций ботов (Telegram, MAX и Instagram) в сервисе retensy /bots: из текстового описания → валидный граф сценария → заливка и публикация через API.
Быстрый старт
-
Получи токен. Залогинься на https://bots.retensy.com → открой
/bots/mcp-tokens→ создай токен → скопируй секретzmcp_...(показывается один раз). -
Подключи у своего клиента (env-переменные везде одни и те же:
RETENSY_BASE_URL,RETENSY_MCP_TOKEN):Claude Desktop — добавь в
claude_desktop_config.json:{ "mcpServers": { "retensy-mcp": { "command": "npx", "args": ["-y", "@retensy/mcp@latest"], "env": { "RETENSY_BASE_URL": "https://bots.retensy.com", "RETENSY_MCP_TOKEN": "zmcp_ваш_токен" } } } }Claude Code — одной командой:
claude mcp add retensy-mcp -e RETENSY_BASE_URL=https://bots.retensy.com -e RETENSY_MCP_TOKEN=zmcp_ваш_токен -- npx -y @retensy/mcp@latestИли как плагин (подтянет и скиллы, см. «Вариант A» ниже):
/plugin marketplace add retensy/retensy-mcp /plugin install retensy-mcp@retensyCursor — Settings → MCP → Add new MCP Server (или
.cursor/mcp.jsonв проекте) — тот же JSON-объект, что и для Claude Desktop выше (mcpServers.retensy-mcpсcommand/args/env). -
Собери первую воронку. Опиши сценарий словами агенту — он сам соберёт граф и опубликует (см. «Использование»), либо перенеси готовую воронку из другого сервиса — см. «Перенос воронки из другого конструктора» ниже.
Проверить подключение в любом клиенте: спроси агента «настрой подключение» — вызовет setup и подскажет, если что-то не так.
- 🤖 Сценарии ботов:
list_bots,list_graphs,list_channels,get_graph,create_graph,update_graph,edit_graph_live,patch_graph,dry_run,publish_graph,unpublish_graph,import_funnel,list_templates,create_graph_from_template,clone_graph,copy_graph,rename_graph,set_active_graph,delete_graph,upload_file,list_files,delete_file,graph_analytics,list_bot_users,list_links(+setup/set_token). - 🔌 Боты и сервисы:
create_bot(Telegram/MAX по токену),bot_stop/bot_resume,connect_integration/disconnect_integration(amoCRM, Битрикс24, GetCourse, Я.Метрика, ЮKassa; Google Таблицы — ссылкой на вход Google; креды хранятся зашифрованными и не возвращаются),integration_catalog/integration_status/integration_test(каталог Integration Core и живая проверка подключения),integration_ingress_url(URL ингресса «Внешних событий» — Tilda, JivoSite, WooCommerce, amoCRM, Битрикс24, GetCourse, CloudPayments, Robokassa, Т-Банк, Prodamus — дляTRIGGER_WEBHOOK),channel_post(пост в канал Telegram/MAX). - 📣 Рассылки:
broadcast_preview(размер аудитории),broadcast_send(сейчас или по расписанию, сразу по нескольким ботам; сообщения или запуск сценария; полный фильтр аудиторииaudienceFilter, дедупdedupи распределённый запускstaggerпо ботам),broadcast_list/broadcast_get/broadcast_cancel, повторяющиеся (broadcast_recurring), черновики (broadcast_drafts,broadcast_duplicate), мульти-бот группы (broadcast_group— preview/list/get/pause/resume/cancel) + скиллsend-broadcast. - 👥 Аудитория подписчиков:
audience_search/audience_fields— кросс-бот поиск и фильтр (теги, даты, статус, условия по переменным), / — массовое редактирование тегов/переменных, — потоковая выгрузка выборки в CSV/XLSX, — поиск по «Диалогам» (включая текст сообщений).
Поддерживаемые платформы
Установка
Вариант A — как плагин Claude Code (рекомендуется)
/plugin marketplace add retensy/retensy-mcp
/plugin install retensy-mcp@retensy
Подтянутся MCP-сервер и скиллы build-bot-funnel, rebuild-funnel-from-builder, build-site, send-broadcast, build-publication-chain. Проверить: /mcp и /plugin.
Вариант B — как обычный MCP-сервер (Claude Code / Cursor / Windsurf / любой MCP-клиент)
Через npx без установки. Пример конфига (.mcp.json / настройки клиента):
{
"mcpServers": {
"retensy-mcp": {
"command": "npx",
"args": ["-y", "@retensy/mcp@latest"],
"env": {
"RETENSY_BASE_URL": "https://bots.retensy.com",
"RETENSY_MCP_TOKEN": "zmcp_ваш_токен"
}
}
}
}
См. также examples/.mcp.json.
Авторизация — персональный токен
Токен действует от твоего имени в пределах выбранных прав (см. «Права токена» ниже).
- Залогинься на https://bots.retensy.com → открой
/bots/mcp-tokens. - Выбери права токена (пресет «Только чтение», «Полный доступ» или свой набор) и, при желании, срок действия → создай токен → скопируй секрет
zmcp_...(показывается один раз). - Передай токен любым способом:
- просто пришли его агенту в чат — он вызовет инструмент
set_tokenи сохранит токен в~/.retensy-bot-graph/token(применяется сразу, без рестарта), или envв.mcp.json(Вариант B), или- переменной окружения: PowerShell
setx RETENSY_MCP_TOKEN "zmcp_...", bashexport RETENSY_MCP_TOKEN="zmcp_...".
- просто пришли его агенту в чат — он вызовет инструмент
Отозвать токен можно там же — доступ блокируется мгновенно.
С 14.10 тот же токен
zmcp_...полностью покрывает и вебхук-сценарии (/api/scenarios—scenario_*), и управление подключениями сервисов (/api/integrations—connect_integration/disconnect_integration/integration_updateи остальныеintegration_*), не только/api/bots. Отдельного токена под эти инструменты не нужно.
Права токена (scopes)
С 17.10.2026 у токена есть права. Их проверяет сервер на каждом запросе, а не MCP-клиент, поэтому прямой вызов API (curl и т.п.) их тоже не обходит; MCP-клиент только объясняет отказ. Но права крупные — выдавай токену только то, что нужно для задачи.
- Пресеты: «Только чтение» =
read; «Полный доступ» = все семь. По умолчанию в кабинете предлагаетсяread+write:bots+write:sites— собирать ботов и сайты. Это не «безопасный» набор: он видит ПДн подписчиков и заявок и меняет живые ответы ботов и ключи интеграций. В нём нет только рассылок, оплаты, удаления и выгрузки. - Цепочки и расписание с одним
write:bots: цепочку можно создать выключенной или с согласованием каждого поста (approvalMode: ALL), сценарий по расписанию, с отправкой в заданный чат/канал (target.modechat/expression) или вебхук-сценарий с получателем из тела запроса (recipientFrom) — оставить черновиком. Включить/опубликовать — нуженbroadcast. То же для сценария с письмом на любой адрес, кроме ровно{{var.email}}подписчика (и если сценарий сам не перезаписываетemail), и для сценария с триггером события Telegram/комментария и шагами отправки — там «ответ в текущий чат» уходит в канал или группу. Правка живого вебхук-сценария и новый секрет живого вебхука, который шлёт людям, тоже требуютbroadcast. - Нет права → сервер отвечает
403 {"error":"insufficient_scope","requiredScope":"…"}, а инструмент возвращает ошибку «Токену не хватает права «X» …». Это не сбой: добавь право токену кнопкой «Изменить права» на/bots/mcp-tokens(действует со следующего запроса, переподключать клиента не нужно) или выпусти новый токен. - Старые токены (выпущены до появления прав) работают как раньше — с полным доступом; в кабинете они помечены «полный доступ (старый токен)». Рекомендуем ограничить им права.
- Срок действия (30/90/365 дней или бессрочно) задаётся при создании; истёкший токен отвечает 401 и не
ротируется (400
token_expired) — выпусти новый. Ротация сохраняет права и длительность срока; API ротации принимает и новые права (scopes/preset) — так старый токен переводят на явные права.
Не знаешь, что делать? Скажи агенту «настрой подключение» — он вызовет
setup, объяснит шаги и попросит токен. Любой инструмент при отсутствии токена тоже вернёт пошаговую инструкцию.
Дев-окружение:
RETENSY_BASE_URL=http://localhost:8066. Fallback без токена:RETENSY_SESSION_COOKIE= значение кукиSESSIONиз браузера.
Использование
Опиши воронку словами — агент соберёт граф и (через MCP) опубликует:
«Собери бота:
/start→ приветствие с кнопкой подписки на канал → вопрос с 3 кнопками (бизнес / эксперт / просто смотрю) → для каждой свою цепочку из 2 сообщений с задержкой 1 день → финал с регистрацией на вебинар. Залей в бота и опубликуй.»
Под капотом скилл соберёт nodes/edges, прогонит локальную проверку и вызовет import_funnel → создаст граф, зальёт узлы, прогонит dry-run /start, опубликует. При ошибках публикации — разберёт по code/nodeId, починит, повторит.
Инструменты
Рассылки
Сообщение рассылки — как в мастере кабинета: {type, text?, mediaUrl?, mediaUrls?, buttons?}, до 5 сообщений.
- HTML:
<b> <i> <u> <s> <code> <pre> <blockquote> <tg-spoiler> <a href="https://…">, перенос строки —\n. - Кнопки только URL
[{text, url}]— callback-кнопок в рассылке нет. Медиа — сначалаupload_file, потом егоurl. - Аудитория — подписчики бота, фильтр тегами:
tagsAll(есть все),tagsNone(нет ни одного). До 50 000 на бота, до 20 ботов одного владельца за раз. scheduledAt— ISO 8601; без часового пояса считается московским. Пусто — отправить сейчас.- Рассылки — на платном тарифе; квота получателей месячная. При нехватке — ошибка с прямой ссылкой на смену тарифа.
- У Instagram-ботов рассылок нет.
{"name": "Распродажа", "botIds": ["<id>"], "tagsAll": ["клиент"], "scheduledAt": "2026-10-10T10:00",
"messages": ["<b>Только сегодня</b> — скидка 30%",
{"type": "PHOTO", "mediaUrl": "https://…/sale.jpg", "text": "Успей до полуночи",
"buttons": [{"text": "В магазин", "url": "https://shop.example"}]}]}
Когда нужен браузер
Через API не делается то, что требует входа пользователя у стороннего сервиса, оплаты или входа в аккаунт.
Такие инструменты не падают, а возвращают {needsBrowser: true, url, instruction} или ошибку со ссылкой:
Формат графа и проверка
Граф — контейнер retensy-bot-graph (nodes[] + edges[]). Полная схема узлов/хэндлов и правила валидатора — в скилле:
Локальная проверка графа перед заливкой:
# Telegram (по умолчанию)
node skills/build-bot-funnel/validate.mjs path/to/import.json
# Instagram-бот
node skills/build-bot-funnel/validate.mjs path/to/import.json --platform=INSTAGRAM
# MAX-бот
node skills/build-bot-funnel/validate.mjs path/to/import.json --platform=MAX
Перенос воронки из другого конструктора
Есть готовая воронка в BotHelp, SaleBot, Senler, Leadteh, Smartsender, ManyChat, PuzzleBot или
любом другом сервисе — скилл rebuild-funnel-from-builder
учит агента перенести её в Retensy: разобрать export JSON/текст/скриншоты/пересказ → построить
инвентарь блоков → сопоставить с реальными типами узлов Retensy (таблица в
reference/mapping.md) → прямо спросить
про то, что не мапится, вместо того чтобы выдумывать замену → собрать граф → проверить
validate.mjs/dry_run → залить новым черновиком (никогда не поверх текущего сценария) →
опубликовать только после явного подтверждения. Перенос самих подписчиков (не графа) — отдельно,
через migration_presets/migration_preview/migration_commit (CSV).
Разработка
git clone https://github.com/retensy/retensy-mcp
cd retensy-mcp
RETENSY_MCP_TOKEN=zmcp_... node src/index.mjs # стартует stdio MCP-сервер
Зависимостей нет — это голый JSON-RPC по stdio (протокол MCP 2024-11-05).
Обновления
При старте сервер сверяет свою версию с npm (результат кэшируется на 6 часов в
~/.retensy-bot-graph/update-check.json). Если вышла новая — уведомление появится в setup и
в первом ответе инструмента.
- Установка через npx (вариант B): держите в конфиге
@retensy/mcp@latest— тогда свежая версия подтягивается при запуске. Если пакет установлен глобально, сервер сам запуститnpm i -g @retensy/mcp@latestв фоне (отключаетсяRETENSY_MCP_AUTOUPDATE=0). - Установка как плагин (вариант A): обновляйте плагин/
git pull— npm тут не при чём, исполняется файл репозитория.
Важно: запущенный процесс не может подменить собственный код — обновление вступает в силу после перезапуска MCP-сервера. Нет сети или npm недоступен — проверка молча пропускается, работа не ломается.
Отчёты о неудачах (телеметрия)
Чтобы мы узнавали, каких возможностей не хватает, при неудаче инструмента отправляется анонимный
отчёт: неизвестный инструмент, отказ публикации (errors[]), ошибка API.
Отчёт уходит на POST {RETENSY_BASE_URL}/api/mcp/report — то есть на тот же сервер, с которым
вы и так работаете. Адреса чата/вебхука, куда мы складываем отчёты, в пакете нет: он живёт в
переменной окружения на сервере. Так его нельзя вытащить из пакета и залить, а мы можем сменить
приёмник без выпуска новой версии.
Что уходит: имя инструмента, категория неудачи, текст ошибки, ключи аргументов, версия, платформа
и анонимный id установки (хэш от имени хоста и домашнего каталога — не сами значения).
Что НЕ уходит никогда: токены, cookie, пароли, креды интеграций, содержимое графов и текстов
рассылок. Значения аргументов по умолчанию скрыты — присылаются только безопасные поля вроде
graphId/botId/kind.
Если персональный токен настроен, он прикладывается к отчёту — тогда мы видим, у кого именно
не хватило возможности, и можем ответить. Токен прикладывается только когда приёмник совпадает
с RETENSY_BASE_URL: на сторонний RETENSY_MCP_REPORT_URL он не отправляется.
Отчёты дедуплицируются и ограничены 20 на запуск, отправка не блокирует ответ инструмента (таймаут 4 с) и при сбое сети молча игнорируется. На сервере — свои лимиты (30 в час с адреса, 500 в час всего), так что отчёты нельзя использовать для заливки.
Отдельно: если токен ещё не настроен вовсе, отчёт не отправляется — это обычное состояние нового пользователя, а не пробел в возможностях.
Работа партнёра с несколькими проектами
Партнёр настраивает MCP один раз, своим собственным токеном — дальше тот же токен работает со всеми проектами, доступ к которым ему дали клиенты.
- Токен = аккаунт, не проект.
zmcp_...всегда идентифицирует тебя. Он не привязан к конкретному боту или сайту — какие проекты видны и что с ними можно делать, решает не токен, а твоя роль в каждом отдельном проекте. - Доступ — через приглашение, а не передачу токена. Чтобы ты поработал в боте клиента, клиент сам приглашает тебя соредактором (в боте → «Доступ» → email или ссылка, роль Viewer/Editor/Admin). Свой MCP-токен или пароль клиент никогда не присылает — и ты его не просишь.
list_botsиsite_listпоказывают всё сразу: твои собственные проекты и те, куда тебя пригласили — у чужих в ответе естьownerName(имя владельца) иaccessRole(твоя роль в этом конкретном проекте: OWNER / ADMIN / EDITOR / VIEWER). Так ты сразу видишь, где ты владелец, а где гость с ограниченной ролью.- Передавай
botId/siteIdявно в каждом вызове инструмента — ассистент не хранит «текущий проект». Переключение между проектами клиентов — это просто другойbotIdв следующем вызове, оно не меняет твой аккаунт и не путает данные между проектами. - Доступ проверяется заново на каждый запрос. Если клиент поменял тебе роль или вовсе убрал из соредакторов, следующий же вызов к этому проекту откажет — без повторной настройки токена и без задержки.
- Бери минимально нужную роль. Viewer — чтобы посмотреть и оценить задачу, Editor — чтобы собирать и публиковать сценарии, Admin — только если по договорённости настраиваешь рассылки или параметры бота.
- Никогда не проси пароль от аккаунта клиента или его MCP-токен. Единственный штатный способ работать в чужом проекте — приглашение с ролью; свой токен отзывай сам в кабинете, если он утёк.
Безопасность
Токен = доступ к аккаунту по API в пределах его прав. Выдавай агенту минимально нужные права (для знакомства — «Только чтение»). Не коммить токен; держи в env. В конфигах храни ссылку ${RETENSY_MCP_TOKEN}, не само значение.
Лицензия
MIT — см. LICENSE.
