Evomi MCP Server

Un servidor del Model Context Protocol (MCP) para las API de proxy y web scraping de Evomi. Ofrece a asistentes de IA como Claude acceso directo a una cuenta de proxy —credenciales, cadenas de conexión, segmentación geográfica, uso, rotación de sesiones— junto con un completo kit de scraping para rastrear sitios web y extraer datos estructurados.

39 herramientas por defecto, 40 con EVOMI_ENABLE_SPENDING=1.

Características

Gestión de proxy y cuenta

• Credenciales de proxy - Nombre de usuario y contraseña para cada producto de la cuenta

• Cadenas de conexión - Cadenas con segmentación geográfica y sesión fija, con un comando curl para comprobarlas

• Listas de proxy masivas - Hasta 50 endpoints por llamada

• Segmentación geográfica - Busca los países, regiones, ciudades e ISP que ofrece realmente un producto

• Uso y saldo - Ancho de banda en 24h, 3d y 7d, en total y por bucket

• Control de sesiones - Rota una sesión fija a una nueva IP de salida

• Perfiles de navegador - Lista los perfiles de huella guardados y pide más con un opt-in

• Acceso al servicio - Créditos de Scraper y Browser, concurrencia y endpoints

Web scraping

• Scraping de una sola página - Extrae cualquier URL con detección automática de JavaScript

• Rastreo de sitios web - Rastreo multipágina con control de profundidad

• Descubrimiento de URLs - Encuentra URLs mediante sitemaps, CommonCrawl o rastreo dentro del sitio

• Búsqueda de dominios - Encuentra dominios buscando en la web

• Extracción con IA - Usa IA para extraer datos estructurados de páginas

• Agente conversacional - Interfaz en lenguaje natural para tareas de scraping

• Gestión de configuraciones - Guarda y reutiliza configuraciones de scraping

• Gestión de esquemas - Define y prueba esquemas de extracción

• Configuración de almacenamiento - Gestiona el almacenamiento en la nube para los datos extraídos

• Tareas programadas - Automatiza el scraping con una programación

Instalación

pip install evomi-mcp

Requiere Python 3.10 o superior. El servidor funciona con las dos versiones principales del SDK mcp (>=1.8.0,<3), por lo que se instala tanto en un entorno ya fijado a 1.x como en uno nuevo que resuelve 2.x.

Ejecuta evomi-mcp --help para ver las variables de entorno que lee, o evomi-mcp --version para ver la versión instalada. Sin argumentos, habla MCP sobre stdio, que es como un cliente MCP lo inicia.

Configuración

Una sola credencial es suficiente:

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

Tómala de Settings > API para una cuenta personal, o de Settings > Team para una de equipo. Autentica directamente las herramientas de proxy y de cuenta, y las herramientas de scraping se autentican con la clave de scraper de la cuenta, que el servidor lee de la Public API en la primera llamada de scraping y mantiene en memoria durante el proceso. Nunca se escribe en disco ni aparece en la salida de las herramientas.

Cuando una variable específica está definida, prevalece sobre EVOMI_API_KEY. Establecer solo una clave de scraper también funciona, pero entonces las herramientas de proxy y de cuenta necesitan también EVOMI_PUBLIC_API_KEY, ya que una sola clave no puede servir para ambas APIs.

Ajustes opcionales:

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

Credenciales en la salida de las herramientas

get_proxy_credentials, build_proxy_connection_string y generate_proxy_list devuelven contraseñas de proxy reales, que es para lo que sirven, y get_api_access devuelve una clave de API de servicio cuando se le pide con include_api_key. El resto de herramientas devuelven únicamente saldos, endpoints, uso y datos de segmentación.

Hay tres cosas que lo limitan. Esas cuatro herramientas llevan una instrucción en sus descripciones para no repetir el valor a menos que se pida directamente —la especificación MCP no tiene ninguna anotación para un resultado sensible, así que la descripción es el único canal que llega al modelo—. generate_proxy_list y build_proxy_connection_string devuelven como máximo 50 entradas por llamada, muy por debajo de las 500 que permite la Public API, y rechazan una petición mayor en lugar de recortarla. Y EVOMI_HIDE_PROXY_PASSWORDS=1 desactiva la divulgación por completo:

Las dos que rechazan lo hacen porque toda su salida es la credencial: una cadena de conexión con una contraseña enmascarada no puede conectarse. El rechazo señala a list_proxy_products y list_proxy_targeting_options, que proporcionan el hostname de la puerta de enlace, los puertos y los valores de segmentación sin ninguna credencial, y las descripciones que ve el modelo también cambian.

EVOMI_ENABLE_SPENDING=1 es lo contrario, un opt-in para la única herramienta que cuesta dinero. Sin ella, order_browser_profile no está registrada en absoluto, por lo que el modelo conectado nunca la ve.

Anotaciones de herramientas

Toda herramienta establece los cuatro indicadores de la especificación MCP. destructiveHint y openWorldHint tienen true por defecto, de modo que una herramienta que los omita se anuncia a sí misma como potencialmente destructiva y como capaz de alcanzar un mundo externo sin límites.

openWorldHint es true para las herramientas que alcanzan una dirección elegida por quien llama (scrape_url, crawl_website, map_website, search_domains, agent_request, y las herramientas de esquema y configuración que validan contra la página que describen), y false para todo lo que solo habla con los endpoints propios de Evomi. readOnlyHint es false para las herramientas que crean, actualizan, eliminan, alternan, rotan o piden algo. El prefijo MUTATING en rotate_proxy_session y order_browser_profile está también en la descripción, porque la descripción llega a todos los modelos, mientras que una anotación solo llega a un cliente que la lea.

Uso con Claude Desktop

Añade a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

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

O si está instalado desde el código fuente:

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

Herramientas disponibles

Proxy y cuenta (9 herramientas, Evomi Public API, + 1 opt-in)

Operaciones de scraping (6 herramientas)

Gestión de configuraciones (6 herramientas)

Gestión de esquemas (6 herramientas)

Gestión de almacenamiento (4 herramientas)

Gestión de Programaciones (7 herramientas)

Cuenta (1 herramienta)

Ejemplos de Herramientas

Scraping

// 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}]}

Rastreo

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

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

Búsqueda de Dominios

// 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}

Gestión de Configuraciones

// 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"}

Programación

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

Créditos

Las operaciones de scraping consumen créditos, y el costo de una llamada depende del modo en el que se ejecuta y de las opciones que lleva. Las tarifas actuales están en docs.evomi.com; get_api_access informa el saldo de la cuenta.

Cada respuesta de scraping incluye credits_used y credits_remaining, por lo que el costo de una llamada es visible en su propio resultado.

Desarrollo

Configuración

pip install -e ".[dev]"

Ejecutar el Servidor Directamente

evomi-mcp
# or
python -m evomi_mcp.server

Pruebas

pytest

El conjunto de pruebas se ejecuta contra ambas versiones principales de mcp, y CI lo ejecuta en cada una de ellas en las versiones de Python compatibles.

Publicación

La versión se declara tanto en pyproject.toml como en src/evomi_mcp/__init__.py, y CI falla si no coinciden. Publicar una GitHub Release etiquetada vX.Y.Z compila los artefactos, ejecuta el conjunto de pruebas contra la rueda compilada y sube a PyPI mediante Trusted Publishing, por lo que no hay ningún token en ningún lugar.

Enlaces

• Sitio web de Evomi

• Panel de Evomi

• Documentación de la API

Licencia

MIT — consulte LICENSE.