Evomi MCP Server

一个用于 Evomi 代理和网页抓取 API 的模型上下文协议（MCP）服务器。它让 Claude 等 AI 助手可以直接访问代理账户 — 凭据、连接字符串、地理定位、用量、会话轮换 — 同时提供完整的抓取工具集，用于爬取网站和提取结构化数据。

默认情况下有 39 个工具，设置 EVOMI_ENABLE_SPENDING=1 后有 40 个。

功能特性

代理与账户管理

• 代理凭据 - 账户上每个产品的用户名和密码

• 连接字符串 - 地理定位、会话固定的字符串，附带用于检查的 curl 命令

• 批量代理列表 - 每次调用最多 50 个端点

• 地理定位 - 搜索产品实际提供的国家、地区、城市和 ISP

• 用量与余额 - 24 小时、3 天和 7 天的带宽，按总量和每个存储桶分别统计

• 会话控制 - 将粘性会话轮换到新的出口 IP

• 浏览器配置文件 - 列出已保存的指纹配置文件，并可在选择加入后订购更多

• 服务访问 - Scraper 和 Browser 的额度、并发数和端点

网页抓取

• 单页抓取 - 使用自动 JavaScript 检测抓取任意 URL

• 网站爬取 - 支持深度控制的多页爬取

• URL 发现 - 通过站点地图、CommonCrawl 或站内爬取查找 URL

• 域名搜索 - 通过网络搜索查找域名

• AI 驱动的提取 - 使用 AI 从页面中提取结构化数据

• 对话式代理 - 用于抓取任务的自然语言界面

• 配置管理 - 保存并复用抓取配置

• 模式管理 - 定义并测试提取模式

• 存储配置 - 管理抓取数据的云存储

• 定时任务 - 按计划自动执行抓取

安装

pip install evomi-mcp

需要 Python 3.10 或更高版本。服务器可在 mcp SDK 的两个主要版本（>=1.8.0,<3）上运行，因此它既可以安装到已锁定 1.x 的环境中，也可以安装到解析为 2.x 的全新环境中。

运行 evomi-mcp --help 可查看它读取的环境变量，或运行 evomi-mcp --version 查看已安装的版本。不带任何参数时，它通过 stdio 进行 MCP 通信，这也是 MCP 客户端启动它的方式。

配置

一份凭据就足够了：

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

个人账户可从设置 > API获取，团队账户则从设置 > 团队获取。它直接对代理和账户工具进行身份验证，而抓取工具使用账户的 scraper 密钥进行身份验证，服务器会在首次抓取调用时从 Public API 读取该密钥，并在进程内存中保留。它永远不会写入磁盘，也永远不会出现在工具输出中。

设置特定变量后，它会优先于 EVOMI_API_KEY。仅设置 scraper 密钥也可以，但代理和账户工具还需要同时设置 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 在使用 include_api_key 请求时会返回服务 API 密钥。其他所有工具仅返回余额、端点、用量和定位数据。

有三件事对此加以约束。这四个工具的描述中带有指示：除非被直接要求，否则不得重复输出该值 — MCP 规范没有针对敏感结果的注解，因此描述是唯一能到达模型的渠道。generate_proxy_list 和 build_proxy_connection_string 每次调用最多返回 50 条记录，远低于 Public API 允许的 500 条，并且会拒绝更大的请求，而不是将其截断。而 EVOMI_HIDE_PROXY_PASSWORDS=1 则完全关闭披露功能：

这两个拒绝的工具之所以这样做，是因为它们的整个输出就是凭据本身：带有屏蔽密码的连接字符串无法连接。拒绝时会指向 list_proxy_products 和 list_proxy_targeting_options，它们提供网关主机名、端口和定位值，其中不包含任何凭据，模型看到的描述也会随之改变。

EVOMI_ENABLE_SPENDING=1 则相反，它是对唯一一个花钱的工具的选择加入。没有它，order_browser_profile 根本不会被注册，因此所连接的模型永远不会看到它。

工具注解

每个工具都设置了 MCP 规范的全部四个提示。destructiveHint 和 openWorldHint 默认值为 true，因此省略这两个提示的工具会将自身标示为具有潜在破坏性，并且会触及无边界的外部世界。

对于触及调用者所选地址的工具（scrape_url、crawl_website、map_website、search_domains、agent_request，以及针对其所描述页面进行验证的模式和配置工具），openWorldHint 为 true；对于所有只与 Evomi 自身端点通信的工具，则为 false。对于创建、更新、删除、切换、轮换或订购某些内容的工具，readOnlyHint 为 false。rotate_proxy_session 和 order_browser_profile 上的 MUTATING 前缀也出现在描述中，因为描述能到达每个模型，而注解只能到达读取它的客户端。

与 Claude Desktop 配合使用

添加到你的 Claude Desktop 配置中（macOS 上：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "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 会失败。发布标记为 vX.Y.Z 的 GitHub Release 会构建产物，针对构建好的 wheel 运行测试套件，并通过 Trusted Publishing 上传到 PyPI，因此任何地方都没有令牌。

链接

• Evomi 官网

• Evomi 仪表盘

• API 文档

许可证

MIT — 参见 LICENSE。