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
Для текущего проекта (рекомендуется):
claude mcp add afina --scope project -e AFINA_API_KEY=ВАШ_КЛЮЧ -e AFINA_URL=http://localhost:50778 -- npx -y afina-mcpДля всех проектов текущего пользователя:
claude mcp add afina --scope user -e AFINA_API_KEY=ВАШ_КЛЮЧ -e AFINA_URL=http://localhost:50778 -- npx -y afina-mcpПроверка подключения:
claude mcp listafina: npx -y afina-mcp - ✓ ConnectedCodex CLI и другие CLI-клиенты
CLI-клиенты без встроенной команды mcp add подключают MCP через конфиг-файл. Для Codex CLI это ~/.codex/config.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-ключ и отправьте агенту - он выполнит все шаги сам.
Настрой подключение к 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.
{
"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" может быть опциональным - некоторые клиенты определяют transport автоматически, если задан command. Если клиент не распознает конфиг, проверьте документацию для конкретной версии.
Конфиг-файлы, которые содержат AFINA_API_KEY, нужно исключать из системы контроля версий. Для командной работы храните ключ в менеджере секретов или переменных окружения CI/CD.
Как агент вызывает инструменты#
Когда Вы пишете агенту "покажи список аккаунтов", Claude Code не выполняет shell-команды самостоятельно. Он отправляет JSON-RPC вызов в stdin процесса afina-mcp.
{"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 вручную.
$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-mcpLive-ответ 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.
Практические сценарии#
Проверить все прокси перед запуском активности#
Проверь все прокси в Afina.
Покажи, сколько живых, сколько не отвечают, и какие имеют задержку больше 3 секунд.
Мертвые не удаляй без моего подтверждения.Агент вызывает check_all_proxies, группирует результаты по result.status, показывает медленные прокси отдельно и не переходит к destructive action без подтверждения.
Запустить браузер и прочитать страницу без RPA-скрипта#
Открой аккаунт NEW ACC101.
Зайди на okx.com/boost.
Прочитай активные задания на странице, сделай скриншот и закрой браузер.Типичный flow: resolve_account → start_browser → навигация через eval_in_browser или CDP → get_page_text → take_screenshot → stop_browser.
Запустить скрипт на группе аккаунтов#
Запусти скрипт "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.
Разобрать ошибки выполнения#
Прочитай логи последнего запуска группы "Bybit promo".
Сгруппируй ошибки по типу, покажи проблемные аккаунты и предложи минимальную правку.Агент использует list_task_groups, get_task_group, get_task_group_tasks и get_task_logs. Если причина в скрипте, он читает get_script; если причина в прокси, вызывает check_proxies для конкретных аккаунтов.
Обновить JS-модуль после изменения API#
Обнови модуль 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#
Импортируй профили 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#
Подключись к 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 |
Минимальный чек-лист#
[ ] Afina запущена локально
[ ] API-ключ скопирован из Afina
[ ] Node.js 18+ и npx доступны
[ ] Выполнено claude mcp add afina ...
[ ] .mcp.json добавлен в .gitignore
[ ] claude mcp list показывает Connected
[ ] Claude Code перезапущен
[ ] tools/list показывает инструменты AfinaПосле этого агент может работать с Afina как с управляемой системой: читать состояние, запускать браузеры, создавать задачи, анализировать логи, редактировать скрипты и переносить сессии без ручного копирования между интерфейсами.