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" може бути опціональним - деякі клієнти визначають транспорт автоматично, якщо задано 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 як із керованою системою: читати стан, запускати браузери, створювати задачі, аналізувати логи, редагувати скрипти й переносити сесії без ручного копіювання між інтерфейсами.