Afina MCP Server#
MCP-сервер Afina подключает AI-агента к локальному HTTP API Afina через стандартный Model Context Protocol. Агент получает не "чат с подсказками", а набор реальных инструментов: чтение аккаунтов и скриптов, запуск браузеров, проверку прокси, работу с RPA-модулями, группами задач, логами, cookies и миграцией из других антидетект-браузеров.
- Transport:
stdio - Пакет:
npx -y afina-mcp - Afina API:
http://localhost:50778илиhttp://127.0.0.1:50778 - Аутентификация: переменная окружения
AFINA_API_KEY - Live-проверка:
afina-mcpвозвращаетTools: 92, resources: 5
Как работает Afina MCP#
Afina MCP Server - это stdio-сервер для AI-клиентов, который транслирует MCP-вызовы в HTTP-запросы к локальному API Afina. Когда Afina запущена, десктопное приложение поднимает локальный HTTP-сервер на порту 50778; если порт занят, Afina пробует следующие порты в диапазоне.
AI-клиент не ходит в базу Afina напрямую и не редактирует файлы профилей вручную. Он вызывает MCP tool, afina-mcp проверяет аргументы, делает HTTP-запрос к Afina с x-api-key, получает ответ и возвращает его агенту в формате MCP.
afina-mcp - это отдельный npm-пакет. Он не хранит состояние сессии Afina и живет столько, сколько его держит запущенным MCP-клиент.
Предварительные требования#
Перед подключением проверьте локальное окружение.
| Что | Как проверить | Зачем нужно |
|---|---|---|
| Afina запущена | приложение открыто локально | Поднимает HTTP API |
| API-ключ Afina | Настройки → Основные → API ключ | Передается как AFINA_API_KEY |
| Node.js 18+ | node --version | Запускает npx |
| npx | npx --version | Загружает afina-mcp |
| Claude Code | claude --version | MCP-клиент для подключения |
Без валидного AFINA_API_KEY большинство /api/* endpoint-ов Afina вернут 401 Unauthorized или закроют соединение. MCP-сервер тоже не стартует корректно без этой переменной.
Подключение через CLI#
Afina MCP подключается к любому AI-агенту одинаково: клиент запускает npx -y afina-mcp как локальный процесс с транспортом stdio и получает доступ ко всем 92 инструментам Afina через переменную AFINA_API_KEY. Разница между клиентами - только в том, где хранится конфиг.
Claude Code
Для текущего проекта (рекомендуется):
Для всех проектов текущего пользователя:
Проверка подключения:
Codex CLI и другие CLI-клиенты
CLI-клиенты без встроенной команды mcp add подключают MCP через конфиг-файл. Для Codex CLI это ~/.codex/config.yaml:
Для Gemini CLI - ~/.gemini/settings.json или .gemini/settings.json в проекте (JSON-формат в следующем разделе).
Подключение через агента#
Не хотите вводить команды вручную? Скопируйте промпт ниже, замените [ВСТАВИТЬ_КЛЮЧ] на свой API-ключ и отправьте агенту - он выполнит все шаги сам.
Если Вы используете --scope project, добавьте .mcp.json в .gitignore. В этом файле хранится AFINA_API_KEY, поэтому его нельзя коммитить в репозиторий. Аналогично исключайте из git любой конфиг-файл, который содержит ключ.
После подключения перезапустите клиент. MCP tools загружаются во время старта новой сессии - сервер может быть добавлен правильно, но инструменты не появятся до перезапуска.
Настройка конфигурационных файлов#
Если MCP-клиент ожидает JSON-конфиг, используйте стандартный stdio-формат. Он одинаковый для всех клиентов, которые поддерживают спецификацию MCP.
| Клиент | Путь к конфигурации |
|---|---|
| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Cursor | .cursor/mcp.json в корне проекта или ~/.cursor/mcp.json глобально |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| Gemini CLI | .gemini/settings.json в проекте или ~/.gemini/settings.json глобально |
| Cline | Настройки MCP в GUI расширения VS Code |
| Continue | .continue/config.json в проекте |
Поле "type": "stdio" может быть опциональным - некоторые клиенты определяют transport автоматически, если задан command. Если клиент не распознает конфиг, проверьте документацию для конкретной версии.
Конфиг-файлы, которые содержат AFINA_API_KEY, нужно исключать из системы контроля версий. Для командной работы храните ключ в менеджере секретов или переменных окружения CI/CD.
Как агент вызывает инструменты#
Когда Вы пишете агенту "покажи список аккаунтов", Claude Code не выполняет shell-команды самостоятельно. Он отправляет JSON-RPC вызов в stdin процесса afina-mcp.
afina-mcp превращает это в HTTP-запрос к локальной Afina, добавляет x-api-key, получает JSON-ответ и возвращает его агенту.
Для прямой диагностики без перезапуска Claude Code можно выполнить tools/list вручную.
Live-ответ tools/list подтверждает 92 инструмента и 5 resources. Если локальный список отличается, приоритет имеет Ваш текущий afina-mcp, а не эта страница.
Доступные инструменты#
Ниже приведены группы инструментов, подтвержденные live tools/list. Названия tools и параметров остаются на английском, потому что это часть executable API.
Аккаунты и профили#
| Tool | Обязательные параметры | Что делает |
|---|---|---|
list_accounts | - | Возвращает аккаунты с фильтрами groupId, tagId, isRunning |
resolve_account | query | Преобразует UUID, название, numberId или DB id в полный аккаунт |
get_account | accountId | Читает один аккаунт по UUID |
create_account | - | Создает постоянный профиль с fingerprint, proxy, tags, groups, settings |
create_one_time_profile | - | Создает disposable-профиль, запускает браузер и удаляет после остановки |
update_account | - | PATCH-обновление аккаунта по id или accountId |
delete_account | accountId | Soft-delete аккаунта |
hard_delete_account | - | Безвозвратное удаление по id, ids, accountId или accountIds |
Если пользователь просит "временный", "одноразовый", "disposable" или "one-time" профиль, агент должен вызвать create_one_time_profile, а не create_account. Обычный create_account создает постоянный аккаунт.
Браузерная сессия и страница#
| Tool | Обязательные параметры | Что делает |
|---|---|---|
start_browser | profileId | Запускает браузер и возвращает wsEndpoint |
stop_browser | profileId | Закрывает браузер через CDP |
eval_in_browser | profileId, code | Выполняет JavaScript в текущей вкладке |
find_clickable | profileId, text | Ищет кликабельный элемент по тексту |
find_input | profileId, query | Ищет поле ввода |
get_current_url | profileId | Возвращает URL активной вкладки |
get_page_text | profileId | Читает текст страницы, поддерживает selector и maxChars |
take_screenshot | profileId | Делает скриншот текущей вкладки |
Эта группа дает агенту режим "одноразовой AI-сессии": запустить аккаунт, открыть нужную страницу, прочитать текст, сделать скриншот, найти кнопку или поле и закрыть браузер без написания RPA-скрипта.
Cookies#
| Tool | Обязательные параметры | Что делает |
|---|---|---|
set_cookies | accountId, cookies | Ставит cookies в очередь импорта для аккаунта |
export_cookies | - | Экспортирует cookies по id, ids, accountId или accountIds |
set_cookies полезен для переноса авторизованных сессий. Если аккаунт не запущен, cookies применятся при следующем старте браузера.
RPA-скрипты#
| Tool | Обязательные параметры | Что делает |
|---|---|---|
list_scripts | - | Возвращает список скриптов |
get_script | id | Читает полную структуру одного скрипта |
create_script | name, settings | Создает RPA-скрипт |
update_script | id | Обновляет скрипт |
run_script | profileId, scriptId | Запускает скрипт на одном профиле; опционально closeBrowserAfter |
get_run_logs | uuid | Читает логи прямого запуска |
stop_running_script | uuid | Останавливает running script |
Структура скрипта использует settings.elements[], settings.connections[], ровно один start:true и settings.startElement. Перед генерацией сложного скрипта агент должен читать resource afina://docs/rpa-blocks и схему afina://docs/script-schema.
Модули executeModule#
| Tool | Обязательные параметры | Что делает |
|---|---|---|
list_modules | - | Возвращает список JS-модулей |
get_module | - | Читает модуль по id или hash |
create_module | name | Создает модуль и папку с файлами |
update_module | id | Обновляет строку модуля в БД |
resign_module | id | Пересчитывает Ed25519-подпись модуля |
delete_module | - | Soft-delete модуля |
hard_delete_module | - | Удаляет строку и папку модуля |
После редактирования файлов модуля всегда нужен resign_module. Без свежей подписи executor может вернуть modules.error.signature_invalid.
Группы задач, задачи и запуск на массиве аккаунтов#
| Tool | Обязательные параметры | Что делает |
|---|---|---|
list_task_groups | - | Возвращает группы задач |
get_task_group | id | Читает группу задач |
get_task_group_tasks | groupId | Читает задачи конкретной группы |
create_task_group | - | Создает группу с расписанием, timeout и parallelism |
update_task_group | id | Обновляет группу задач |
start_task_group | id | Активирует scheduler группы |
restart_task_group | id | Возвращает завершенные задачи в waiting |
stop_task_group | id | Останавливает группу |
delete_task_group | id | Soft-delete группы |
hard_delete_task_group | - | Безвозвратное удаление группы |
add_tasks_to_group | groupId, scriptId, accountIds | Добавляет задачи в группу |
run_script_on_accounts | scriptId, accountIds | Композитно создает/использует группу и запускает скрипт |
list_tasks | - | Фильтрует задачи по status, groupId, accountId, scriptId, limit |
get_active_tasks | - | Показывает активные задачи |
get_task_logs | taskUuid | Читает логи задачи |
update_task | id | Обновляет status, executeAt, additionalData, sort, tag, description |
delete_tasks | - | Удаляет задачи |
stop_tasks | - | Останавливает задачи, опционально closeBrowser |
Ключевые поля orchestration: schedule, timeFrom, timeTo, scheduleTime, startHour, endHour, isRepeatable, repeatCount, timeout, activeSession, waitForOtherTaskCompletion.
Прокси, email, базы данных и переменные#
| Tool | Обязательные параметры | Что делает |
|---|---|---|
check_proxies | - | Проверяет прокси аккаунтов по accountIds, groupId или tagId |
check_all_proxies | - | Проверяет все сохраненные прокси |
add_proxy | host, port | Добавляет прокси после проверки |
list_emails | - | Возвращает IMAP-учетные данные без паролей |
toggle_email | email, isActive | Включает или выключает IMAP-мониторинг |
list_databases | - | Возвращает подключения к БД |
get_database | id | Читает одно подключение |
create_database | name | Создает подключение к SQLite/Postgres/MySQL/MSSQL/MongoDB/Redis |
update_database | id | Обновляет подключение |
delete_database | - | Soft-delete БД |
hard_delete_database | - | Удаляет строку и файл, если есть filePath |
list_global_vars | - | Возвращает глобальные переменные |
create_global_var | name, value | Создает переменную |
update_global_var | id | Обновляет переменную |
delete_global_var | - | Удаляет переменные |
list_keys | - | Возвращает каталог ключей |
delete_keys | - | Удаляет имена ключей из каталога |
get_account_vars | - | Читает переменные аккаунта по account reference |
set_account_var | key, value | Записывает plain или encrypted переменную |
delete_account_var | key | Удаляет переменную аккаунта |
Для аккаунтов агенту лучше сначала вызвать resolve_account, если пользователь называет аккаунт по имени, номеру или короткой текстовой ссылке. resolve_account возвращает оба поля: UUID accountId и числовой id. UUID подходит для большинства tools (start_browser, get_account, export_cookies и т. д.). Исключение: run_script_on_accounts, add_tasks_to_group и check_proxies принимают числовой id, а не UUID - используйте поле id из ответа resolve_account для этих трех tools.
Миграция из других антидетект-браузеров#
| Tool | Обязательные параметры | Что делает |
|---|---|---|
set_vendor_credentials | vendor, token | Сохраняет токен Vision, AdsPower или Dolphin |
list_vendor_credentials | - | Показывает, какие vendor credentials настроены |
delete_vendor_credentials | vendor | Удаляет vendor credentials |
vision_list_folders | - | Список папок Vision |
vision_list_profiles | folderId | Список профилей Vision |
vision_get_profile | folderId, profileId | Полный профиль Vision |
vision_list_proxies | folderId | Прокси Vision |
vision_export_cookies | folderId, profileId | Cookies Vision |
vision_import_profiles | folderId, profileIds | Bulk-import Vision в Afina |
adspower_list_groups | - | Группы AdsPower |
adspower_list_profiles | - | Профили AdsPower |
adspower_get_profile | userId | Полный профиль AdsPower |
adspower_export_cookies | userId | Cookies AdsPower |
adspower_import_profiles | userIds | Bulk-import AdsPower |
dolphin_whoami | - | Проверка Dolphin token |
dolphin_list_profiles | - | Список профилей Dolphin |
dolphin_get_profile | profileId | Полный профиль Dolphin |
dolphin_export_cookies | profileId | Cookies Dolphin |
dolphin_import_profiles | profileIds | Bulk-import Dolphin |
Импорт поддерживает dryRun, withCookies, tagNames, accountGroupNames и vendor-specific throttling для cookie export.
CDP-инструменты#
| Tool | Обязательные параметры | Что делает |
|---|---|---|
cdp_inspect_browser | port | Читает /json/version у любого Chromium с CDP |
cdp_export_cookies | port или wsEndpoint | Экспортирует cookies через CDP |
migrate_via_cdp | port или wsEndpoint | Создает Afina-аккаунт и переносит cookies из running Chromium |
CDP-подход нужен, когда источник не имеет публичного API для экспорта cookies или когда нужно быстро перенести текущую авторизованную сессию.
Встроенные resources#
Afina MCP также отдает resources. Это не tools для действия, а справочники, которые агент должен читать перед сложными операциями.
| URI | Когда читать |
|---|---|
afina://docs/rpa-blocks | Перед генерацией или редактированием RPA-скрипта |
afina://docs/script-schema | Перед create_script или update_script |
afina://docs/tools-cheatsheet | Когда непонятно, какой MCP tool соответствует запросу |
afina://docs/import-mapping | Перед импортом из Vision, AdsPower, Dolphin, MoreLogin, Octo, Linken Sphere |
afina://docs/new-vendor-template | Когда нужно добавить импорт из нового vendor-а |
Для скриптов и миграций resources являются частью рабочего процесса. Корректный агент сначала читает справочник, а уже потом вызывает write-tool.
Практические сценарии#
Проверить все прокси перед запуском активности#
Агент вызывает check_all_proxies, группирует результаты по result.status, показывает медленные прокси отдельно и не переходит к destructive action без подтверждения.
Запустить браузер и прочитать страницу без RPA-скрипта#
Типичный flow: resolve_account → start_browser → навигация через eval_in_browser или CDP → get_page_text → take_screenshot → stop_browser.
Запустить скрипт на группе аккаунтов#
Агент должен сначала найти скрипт через list_scripts, разрешить аккаунты через resolve_account или list_accounts, а потом использовать run_script_on_accounts с activeSession: 10, schedule: true, timeFrom: "09:00", timeTo: "15:00" и timeout.
Разобрать ошибки выполнения#
Агент использует list_task_groups, get_task_group, get_task_group_tasks и get_task_logs. Если причина в скрипте, он читает get_script; если причина в прокси, вызывает check_proxies для конкретных аккаунтов.
Обновить JS-модуль после изменения API#
Минимальный правильный flow: list_modules → get_module → редактирование модуля через доступный write path → update_module при необходимости → resign_module. Без resign_module модуль может не пройти проверку подписи.
Импортировать профили из Dolphin#
Правильный flow: set_vendor_credentials, если токен еще не сохранен → dolphin_list_profiles → dolphin_import_profiles с dryRun: true → подтверждение → dolphin_import_profiles без dryRun.
Перенести сессию из любого Chromium через CDP#
Агент использует cdp_inspect_browser, затем migrate_via_cdp или связку cdp_export_cookies → create_account → set_cookies.
Безопасность и ограничения#
- Агент не должен видеть зашифрованные значения паролей и секретных переменных; он работает с названиями, metadata и разрешенными API-ответами.
delete_account- это soft-delete, аhard_delete_accountбезвозвратно удаляет строки и файлы профиля.delete_module,delete_task_group,delete_database- это soft-delete; вариантыhard_delete_*физически удаляют данные.create_one_time_profileавтоматически hard-delete-ит профиль после остановки браузера.- Для действий с уничтожением данных стоит просить агента сначала показать список target-объектов и дождаться подтверждения.
.mcp.json,claude_desktop_config.jsonи.cursor/mcp.jsonмогут содержатьAFINA_API_KEY; не публикуйте эти файлы.
Не передавайте агенту "удали все", "очисти все профили" или "hard delete без подтверждения" как первый запрос. Сначала попросите dry-run список: какие accountId, ids, модули или группы будут затронуты.
Troubleshooting#
| Проблема | Вероятная причина | Что сделать |
|---|---|---|
AFINA_API_KEY env is required | Не передана env-переменная | Добавьте -e AFINA_API_KEY=... или env в JSON-конфиг |
401 Unauthorized | Неверный API-ключ | Скопируйте ключ заново из Afina |
afina не появляется в tools | Claude Code не перезапущен | Закройте сессию и откройте новую |
npx: command not found | Node.js или npm не установлены | Установите Node.js 18+ |
| MCP подключен, но Afina tools падают | Afina не запущена или порт другой | Запустите Afina и проверьте AFINA_URL |
| Браузер не стартует | Неверный profileId или аккаунт уже в проблемном состоянии | Используйте resolve_account, затем start_browser с UUID |
| Модуль после редактирования не запускается | Не выполнен resign | Вызовите resign_module |
| Импорт vendor-а не работает | Нет credentials или неправильный baseUrl | Проверьте list_vendor_credentials и set_vendor_credentials |
Минимальный чек-лист#
После этого агент может работать с Afina как с управляемой системой: читать состояние, запускать браузеры, создавать задачи, анализировать логи, редактировать скрипты и переносить сессии без ручного копирования между интерфейсами.