Evomi MCP Server

Evomi のプロキシおよび Web スクレイピング API のための Model Context Protocol (MCP) サーバーです。 Claude のような AI アシスタントに、プロキシアカウントへの直接アクセス（認証情報、接続文字列、ジオターゲティング、使用量、セッションローテーション）を提供するとともに、サイトのクロールと構造化データの抽出のための完全なスクレイピングツールキットも提供します。

デフォルトでは 39 ツール、EVOMI_ENABLE_SPENDING=1 では 40 ツールになります。

機能

プロキシとアカウント管理

• プロキシ認証情報 - アカウント上の各製品のユーザー名とパスワード

• 接続文字列 - ジオターゲティング、セッション固定された文字列。確認用の curl コマンド付き

• バルクプロキシリスト - 1 回の呼び出しで最大 50 エンドポイント

• ジオターゲティング - 製品が実際に提供している国、地域、都市、ISP を検索

• 使用量と残高 - 24 時間、3 日、7 日の帯域幅。合計およびバケットごと

• セッション制御 - スティッキーセッションを新しい出口 IP にローテーション

• ブラウザプロファイル - 保存済みのフィンガープリントプロファイルを一覧表示し、オプトインで追加注文

• サービスアクセス - スクレイパーとブラウザのクレジット、同時実行数、エンドポイント

Web スクレイピング

• 単一ページのスクレイピング - 自動 JavaScript 検出で任意の URL をスクレイピング

• Web サイトのクロール - 深さ制御付きの複数ページクロール

• URL ディスカバリ - サイトマップ、CommonCrawl、サイト内クロールで URL を検索

• ドメイン検索 - Web 検索でドメインを検索

• 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 クライアントがサーバーを起動する方法です。

設定

必要な認証情報は 1 つだけです:

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

個人アカウントの場合は Settings > API から、チームアカウントの場合は Settings > Team から取得します。このキーはプロキシおよびアカウントツールを直接認証し、スクレイピングツールはアカウントのスクレイパーキーで認証します。サーバーは最初のスクレイピング呼び出し時に Public API からそのキーを読み取り、プロセスの間メモリに保持します。ディスクに書き込まれることはなく、ツールの出力に表示されることもありません。

特定の変数が設定されている場合は、それが EVOMI_API_KEY より優先されます。スクレイパーキーだけを設定しても機能しますが、その場合プロキシおよびアカウントツールには EVOMI_PUBLIC_API_KEY も必要です。1 つのキーで両方の 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 キーを返します。他のすべてのツールは、残高、エンドポイント、使用量、ターゲティングデータのみを返します。

これを制限するものが 3 つあります。これら 4 つのツールの説明には、直接要求されない限り値を繰り返さないようにという指示が含まれています。MCP 仕様には機密性の高い結果に対する注釈がないため、説明がモデルに届く唯一のチャネルです。generate_proxy_list と build_proxy_connection_string は、1 回の呼び出しで最大 50 エントリを返します。これは Public API が許可する 500 をはるかに下回り、それより大きい要求は切り詰めるのではなく拒否します。そして EVOMI_HIDE_PROXY_PASSWORDS=1 は開示を完全にオフにします:

拒否する 2 つのツールは、その出力全体が認証情報であるためです。パスワードがマスクされた接続文字列では接続できません。拒否メッセージは list_proxy_products と list_proxy_targeting_options を指し示します。これらは認証情報を含まないゲートウェイのホスト名、ポート、ターゲティング値を提供し、モデルが見る説明も変更されます。

EVOMI_ENABLE_SPENDING=1 はその逆で、費用がかかる 1 つのツールに対するオプトインです。これがないと order_browser_profile はまったく登録されないため、接続されたモデルはそれを見ることができません。

ツールの注釈

すべてのツールは MCP 仕様の 4 つのヒントすべてを設定します。destructiveHint と openWorldHint はデフォルトで true であるため、これらを省略したツールは、潜在的に破壊的であり、境界のない外部世界に到達するものとして自身を宣伝します。

openWorldHint は、呼び出し元が選択したアドレスに到達するツール（scrape_url、crawl_website、map_website、search_domains、agent_request、および説明対象のページに対して検証するスキーマおよび設定ツール）では 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を参照。