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

Для поточного проєкту (рекомендовано):

powershell

claude mcp add afina --scope project -e AFINA_API_KEY=ВАШ_КЛЮЧ -e AFINA_URL=http://localhost:50778 -- npx -y afina-mcp

Для всіх проєктів поточного користувача:

powershell

claude mcp add afina --scope user -e AFINA_API_KEY=ВАШ_КЛЮЧ -e AFINA_URL=http://localhost:50778 -- npx -y afina-mcp

Перевірка підключення:

powershell

claude mcp list

text

afina: npx -y afina-mcp - ✓ Connected

Codex CLI та інші CLI-клієнти

CLI-клієнти без вбудованої команди mcp add підключають MCP через конфіг-файл. Для Codex CLI це ~/.codex/config.yaml:

yaml

mcpServers:
  afina:
    command: npx
    args: ["-y", "afina-mcp"]
    env:
      AFINA_API_KEY: "ВАШ_КЛЮЧ"
      AFINA_URL: "http://localhost:50778"

Для Gemini CLI - ~/.gemini/settings.json або .gemini/settings.json у проєкті (JSON-формат у наступному розділі).

Підключення через агента#

Не хочете вводити команди вручну? Скопіюйте промпт нижче, замініть [ВСТАВИТИ_КЛЮЧ] на свій API-ключ і відправте агенту - він виконає всі кроки сам.

text

Налаштуй підключення до Afina MCP сервера.

Мій API-ключ Afina: [ВСТАВИТИ_КЛЮЧ]
Afina запущена, сервер доступний на http://localhost:50778

Зроби наступне:
1. Виконай команду:
   claude mcp add afina --scope project -e AFINA_API_KEY=[ВСТАВИТИ_КЛЮЧ] -e AFINA_URL=http://localhost:50778 -- npx -y afina-mcp

2. Додай рядок .mcp.json до файлу .gitignore (або створи його, якщо не існує).

3. Перевір підключення:
   claude mcp list
   Якщо бачиш "afina: npx -y afina-mcp - ✓ Connected" - підключення успішне.

4. Нагадай мені перезапустити Claude Code - MCP-інструменти завантажуються тільки при старті нової сесії.

Якщо Node.js не встановлено або Afina не запущена - повідом про це окремо.

Якщо Ви використовуєте --scope project, додайте .mcp.json у .gitignore. У цьому файлі зберігається AFINA_API_KEY, тому його не можна комітити в репозиторій. Аналогічно виключайте з git будь-який конфіг-файл, що містить ключ.

Після підключення перезапустіть клієнт. MCP tools завантажуються під час старту нової сесії - сервер може бути доданий правильно, але інструменти не з'являться до перезапуску.

Налаштування конфігураційних файлів#

Якщо MCP-клієнт очікує JSON-конфіг, використовуйте стандартний stdio-формат. Він однаковий для всіх клієнтів, що підтримують специфікацію MCP.

json

{
  "mcpServers": {
    "afina": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "afina-mcp"],
      "env": {
        "AFINA_API_KEY": "ВАШ_КЛЮЧ",
        "AFINA_URL": "http://localhost:50778"
      }
    }
  }
}

Клієнт	Шлях до конфігурації
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.

json

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_accounts","arguments":{}}}

afina-mcp перетворює це на HTTP-запит до локальної Afina, додає x-api-key, отримує JSON-відповідь і повертає її агенту.

Для прямої діагностики без перезапуску Claude Code можна виконати tools/list вручну.

powershell

$env:AFINA_API_KEY = "ВАШ_КЛЮЧ"
$env:AFINA_URL = "http://localhost:50778"

$init = '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "manual",
      "version": "1.0"
    }
  }
}'
$list = '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

"$init`n$list`n" | npx -y afina-mcp

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.

Практичні сценарії#

Перевірити всі проксі перед запуском активності#

text

Перевір усі проксі в Afina.
Покажи, скільки живих, скільки не відповідають, і які мають затримку понад 3 секунди.
Мертві не видаляй без мого підтвердження.

Агент викликає check_all_proxies, групує результати за result.status, показує повільні проксі окремо і не переходить до destructive action без підтвердження.

Запустити браузер і прочитати сторінку без RPA-скрипта#

text

Відкрий акаунт NEW ACC101.
Зайди на okx.com/boost.
Прочитай активні завдання на сторінці, зроби скриншот і закрий браузер.

Типовий flow: resolve_account → start_browser → навігація через eval_in_browser або CDP → get_page_text → take_screenshot → stop_browser.

Запустити скрипт на групі акаунтів#

text

Запусти скрипт "Bybit promo" на акаунтах NEW ACC1-NEW ACC100.
Паралельно 10 акаунтів.
Вікно запуску 09:00-15:00.
Таймаут 30 хвилин.
Перед стартом покажи, які акаунти потрапили в запуск.

Агент має спочатку знайти скрипт через list_scripts, розв'язати акаунти через resolve_account або list_accounts, а потім використати run_script_on_accounts з activeSession: 10, schedule: true, timeFrom: "09:00", timeTo: "15:00" і timeout.

Розібрати помилки у виконанні#

text

Прочитай логи останнього запуску групи "Bybit promo".
Згрупуй помилки за типом, покажи проблемні акаунти і запропонуй мінімальну правку.

Агент використовує list_task_groups, get_task_group, get_task_group_tasks і get_task_logs. Якщо причина у скрипті, він читає get_script; якщо причина у проксі, викликає check_proxies для конкретних акаунтів.

Оновити JS-модуль після зміни API#

text

Онови модуль captcha_solver.
Старий endpoint: api.2captcha.com/in.php
Новий endpoint: api.2captcha.com/createTask
Після зміни виконай resign.

Мінімальний правильний flow: list_modules → get_module → редагування модуля через доступний write path → update_module за потреби → resign_module. Без resign_module модуль може не пройти перевірку підпису.

Імпортувати профілі з Dolphin#

text

Імпортуй профілі Dolphin з тегом "june".
Поклади їх у групу "migrated-dolphin-june".
Спочатку зроби dryRun і покажи перші 5 mapping results.

Правильний flow: set_vendor_credentials якщо токен ще не збережений → dolphin_list_profiles → dolphin_import_profiles з dryRun: true → підтвердження → dolphin_import_profiles без dryRun.

Перенести сесію з будь-якого Chromium через CDP#

text

Підключись до Chrome на CDP-порту 9222.
Експортуй cookies і створи в Afina профіль "imported-session".

Агент використовує 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`

Мінімальний чек-лист#

text

[ ] Afina запущена локально
[ ] API-ключ скопійовано з Afina
[ ] Node.js 18+ і npx доступні
[ ] Виконано claude mcp add afina ...
[ ] .mcp.json додано в .gitignore
[ ] claude mcp list показує Connected
[ ] Claude Code перезапущено
[ ] tools/list показує інструменти Afina

Після цього агент може працювати з Afina як із керованою системою: читати стан, запускати браузери, створювати задачі, аналізувати логи, редагувати скрипти й переносити сесії без ручного копіювання між інтерфейсами.

Afina MCP Server#

Як працює Afina MCP#

Передумови#

Підключення через CLI#

Підключення через агента#

Налаштування конфігураційних файлів#

Як агент викликає інструменти#

Доступні інструменти#

Акаунти й профілі#

Браузерна сесія й сторінка#

Cookies#

RPA-скрипти#

Модулі executeModule#

Групи задач, задачі й запуск на масиві акаунтів#

Проксі, email, бази даних і змінні#

Міграція з інших антидетект-браузерів#

CDP-інструменти#

Вбудовані resources#

Практичні сценарії#

Перевірити всі проксі перед запуском активності#

Запустити браузер і прочитати сторінку без RPA-скрипта#

Запустити скрипт на групі акаунтів#

Розібрати помилки у виконанні#

Оновити JS-модуль після зміни API#

Імпортувати профілі з Dolphin#

Перенести сесію з будь-якого Chromium через CDP#

Безпека й обмеження#

Troubleshooting#

Мінімальний чек-лист#

Пов'язані терміни глосарія