Evomi MCP Server

Сервер Model Context Protocol (MCP) для API прокси и веб-скрапинга Evomi. Он даёт ИИ-ассистентам вроде Claude прямой доступ к прокси-аккаунту — учётным данным, строкам подключения, геотаргетингу, использованию, ротации сессий — а также полный набор инструментов для скрапинга: обход сайтов и извлечение структурированных данных.

39 инструментов по умолчанию, 40 с EVOMI_ENABLE_SPENDING=1.

Возможности

Прокси и управление аккаунтом

• Учётные данные прокси — имя пользователя и пароль для каждого продукта в аккаунте

• Строки подключения — строки с геотаргетингом и закреплением сессии, а также curl-команда для их проверки

• Массовые списки прокси — до 50 конечных точек за один вызов

• Геотаргетинг — поиск стран, регионов, городов и провайдеров, которые реально предлагает продукт

• Использование и баланс — трафик за 24 часа, 3 дня и 7 дней, суммарно и по бакетам

• Управление сессиями — ротация закреплённой сессии на новый выходной IP

• Профили браузера — список сохранённых профилей отпечатков, заказ дополнительных — по согласию

• Доступ к сервисам — кредиты Scraper и Browser, конкурентность и конечные точки

Веб-скрапинг

• Скрапинг одной страницы — скрапинг любого URL с автоматическим определением JavaScript

• Обход сайтов — многостраничный обход с контролем глубины

• Обнаружение URL — поиск URL через sitemap, CommonCrawl или обход сайта

• Поиск доменов — поиск доменов через веб-поиск

• Извлечение на основе ИИ — извлечение структурированных данных со страниц с помощью ИИ

• Диалоговый агент — интерфейс на естественном языке для задач скрапинга

• Управление конфигурациями — сохранение и повторное использование конфигураций скрапинга

• Управление схемами — определение и тестирование схем извлечения

• Настройка хранилища — управление облачным хранилищем для скрапированных данных

• Плановые задания — автоматизация скрапинга по расписанию

Установка

pip install evomi-mcp

Требуется Python 3.10 или новее. Сервер работает на обеих основных версиях SDK mcp (>=1.8.0,<3), поэтому он устанавливается как в окружение, уже закреплённое за версией 1.x, так и в новое, где разрешается версия 2.x.

Запустите evomi-mcp --help, чтобы увидеть переменные окружения, которые он читает, или evomi-mcp --version, чтобы узнать установленную версию. Без аргументов он общается по MCP через stdio — именно так его запускает MCP-клиент.

Конфигурация

Достаточно одного учётного данного:

export EVOMI_PUBLIC_API_KEY="your-public-api-key"

Возьмите его в Settings > API для личного аккаунта или в Settings > Team для командного. Оно напрямую аутентифицирует инструменты прокси и аккаунта, а инструменты скрапинга аутентифицируются скрапер-ключом аккаунта, который сервер читает из Public API при первом скрапинг-вызове и хранит в памяти процесса. Он никогда не записывается на диск и никогда не появляется в выводе инструментов.

Если задана конкретная переменная, она имеет приоритет над EVOMI_API_KEY. Задать только скрапер-ключ тоже можно, но тогда инструментам прокси и аккаунта понадобится ещё и EVOMI_PUBLIC_API_KEY, поскольку один ключ не может обслуживать оба API.

Необязательные настройки:

export EVOMI_BASE_URL="https://scrape.evomi.com"   # scraper API, default
export EVOMI_PUBLIC_BASE_URL="https://api.evomi.com"  # public API, default
export EVOMI_HIDE_PROXY_PASSWORDS=1  # mask every proxy password and service API key
export EVOMI_ENABLE_SPENDING=1  # register the tools that spend account balance

Учётные данные в выводе инструментов

get_proxy_credentials, build_proxy_connection_string и generate_proxy_list возвращают действующие пароли прокси — это их назначение, а get_api_access возвращает сервисный API-ключ, если запросить его с include_api_key. Все остальные инструменты возвращают только балансы, конечные точки, данные об использовании и таргетинге.

Это ограничивают три вещи. В описаниях этих четырёх инструментов есть указание не повторять значение, если оно не было запрошено напрямую — в спецификации MCP нет аннотации для чувствительного результата, поэтому описание — единственный канал, который доходит до модели. generate_proxy_list и build_proxy_connection_string возвращают не более 50 записей за вызов — значительно меньше 500, которые допускает Public API, — и отказывают в большем запросе, а не усекают его. А EVOMI_HIDE_PROXY_PASSWORDS=1 полностью отключает раскрытие:

Два инструмента, которые отказываются, делают это потому, что весь их вывод — это и есть учётное данное: строка подключения с замаскированным паролем не может подключиться. Отказ указывает на list_proxy_products и list_proxy_targeting_options, которые дают имя хоста шлюза, порты и значения таргетинга без учётных данных, а описания, которые видит модель, тоже меняются.

EVOMI_ENABLE_SPENDING=1 — противоположность: согласие на единственный инструмент, который стоит денег. Без него order_browser_profile вообще не регистрируется, поэтому подключённая модель его никогда не видит.

Аннотации инструментов

Каждый инструмент задаёт все четыре подсказки из спецификации MCP. destructiveHint и openWorldHint по умолчанию равны true, поэтому инструмент, который их опускает, заявляет о себе как о потенциально разрушительном и обращающемся к неограниченному внешнему миру.

openWorldHint равен true для инструментов, которые обращаются к адресу, выбранному вызывающей стороной (scrape_url, crawl_website, map_website, search_domains, agent_request, а также инструменты схем и конфигураций, которые проверяют соответствие странице, которую описывают), и false для всего, что общается только с собственными конечными точками Evomi. readOnlyHint равен false для инструментов, которые создают, обновляют, удаляют, переключают, ротируют или заказывают что-либо. Префикс MUTATING на rotate_proxy_session и order_browser_profile также присутствует в описании, потому что описание доходит до каждой модели, тогда как аннотация — только до клиента, который её читает.

Использование с Claude Desktop

Добавьте в конфигурацию Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json на macOS):

{
  "mcpServers": {
    "evomi": {
      "command": "evomi-mcp",
      "env": {
        "EVOMI_PUBLIC_API_KEY": "your-public-api-key"
      }
    }
  }
}

Или, если установлено из исходников:

{
  "mcpServers": {
    "evomi": {
      "command": "python",
      "args": ["-m", "evomi_mcp.server"],
      "env": {
        "EVOMI_PUBLIC_API_KEY": "your-public-api-key"
      }
    }
  }
}

Доступные инструменты

Прокси и аккаунт (9 инструментов, Evomi Public API, + 1 по согласию)

Операции скрапинга (6 инструментов)

Управление конфигурациями (6 инструментов)

Управление схемами (6 инструментов)

Управление хранилищем (4 инструмента)

Управление расписанием (7 инструментов)

Аккаунт (1 инструмент)

Примеры инструментов

// Basic scrape
{"url": "https://example.com"}

// AI extraction
{"url": "https://example.com/products", "ai_enhance": true, "ai_prompt": "Extract product names and prices"}

// Browser mode with actions
{"url": "https://example.com", "mode": "browser", "js_instructions": [{"click": ".accept-cookies"}, {"wait": 1000}]}

// Basic crawl
{"domain": "example.com", "max_urls": 50}

// With URL filter
{"domain": "example.com", "url_pattern": "/products/", "depth": 3}

// Find domains
{"query": "best e-commerce sites for electronics", "max_urls": 20, "region": "us-en"}

// Up to 10 queries in one call, max_urls applying to each
{"query": ["online bookstores", "book shops UK"], "max_urls": 50}

// Create config
{"name": "Product Scraper", "config": {"mode": "browser", "output": "markdown"}}

// Generate config with AI
{"name": "Amazon Scraper", "prompt": "Scrape product title, price, and reviews from Amazon"}

// Create daily schedule
{"name": "Daily Prices", "config_id": "cfg_abc123", "interval_minutes": 1440, "start_time": "09:00"}

Кредиты

Операции очистки расходуют кредиты, и стоимость вызова зависит от режима, в котором он выполняется, и от его параметров. Текущие тарифы указаны на docs.evomi.com; get_api_access сообщает баланс на аккаунте.

Каждый ответ очистки содержит credits_used и credits_remaining, поэтому стоимость вызова видна в его собственном результате.

Разработка

Настройка

pip install -e ".[dev]"

Запуск сервера напрямую

evomi-mcp
# or
python -m evomi_mcp.server

Тесты

pytest

Набор тестов запускается для обеих основных версий mcp, и CI запускает его на каждой из них для поддерживаемых версий Python.

Релиз

Версия объявлена в pyproject.toml и src/evomi_mcp/__init__.py, и CI завершается ошибкой, если они не совпадают. Публикация GitHub Release с тегом vX.Y.Z собирает артефакты, запускает набор тестов против собранного wheel и загружает на PyPI через Trusted Publishing, поэтому нигде нет токена.

Ссылки

• Веб-сайт Evomi

• Панель управления Evomi

• Документация API

Лицензия

MIT — см. LICENSE.