ZoomEye MCP サーバー

クエリ条件に基づいてネットワーク資産情報を提供するモデルコンテキストプロトコル（MCP）サーバー。このサーバーにより、大規模言語モデル（LLM）は、dorksやその他の検索パラメータを使用してZoomEyeにクエリを実行し、ネットワーク資産情報を取得できます。

この MCP サーバーは、Claude Desktop、Cursor、Windsurf、Cline、Continue、Zed などの AI アシスタントや開発環境と統合され、自然言語による対話を通じてインターネットに接続されたデバイス、サービス、脆弱性を検索および分析できるようになります。

特徴

dorksを使用してZoomEyeにネットワーク資産情報を照会する
パフォーマンスを向上させ、API呼び出しを削減するキャッシュメカニズム
失敗したAPIリクエストの自動再試行メカニズム
包括的なエラー処理とログ記録

利用可能なツール

zoomeye_search - クエリ条件に基づいてネットワーク資産情報を取得します。
- 必須パラメータ:
  - qbase64 (文字列): ZoomEye検索用のBase64エンコードされたクエリ文字列
- オプションパラメータ:
  - page (整数): ビューアセットのページ番号。デフォルトは 1
  - pagesize (整数): ページあたりのレコード数。デフォルトは 10、最大値は 1000
  - fields (文字列): 返されるフィールド（カンマ区切り）
  - sub_type (文字列): データ型。v4、v6、web をサポートします。デフォルトは v4 です。
  - facets （文字列）：統計項目。複数ある場合はカンマで区切る。
  - ignore_cache (boolean): キャッシュを無視するかどうか

使用ガイド

基本的な使い方

サーバーが起動したら、AIアシスタントや開発環境からサーバーとやり取りできるようになります。使い方は以下のとおりです。

上記のインストール方法のいずれかを使用してサーバーを起動します
AIアシスタント（Claude Desktop、Cursor、Windsurf、Cline、Continue、Zedなど）をサーバーを使用するように設定します
自然言語を使用してネットワーク情報を照会する

検索構文ガイド

検索範囲はデバイス (IPv4、IPv6) と Web サイト (ドメイン) をカバーします。
検索文字列を入力すると、システムは、HTTP、SSH、FTP などのさまざまなプロトコルのコンテンツ (HTTP/HTTPS プロトコルヘッダー、本文、SSL、タイトル、その他のプロトコルバナーなど) を含むキーワードを「グローバル」モードで照合します。
検索文字列は大文字と小文字を区別せず、一致のために分割されます（検索結果ページには「分割」テスト機能があります）。== を使用した検索では、大文字と小文字を区別した厳密な構文による一致が強制されます。
検索文字列には引用符を使用してください（例："Cisco System" または 'Cisco System'）。検索文字列に引用符が含まれている場合は、エスケープ文字を使用してください（例：,"a"b）。検索文字列に括弧が含まれている場合は、エスケープ文字を使用してください（例：portinfo()）。

より詳細な検索構文ルールについてはprompts.pyで確認できます。

ZoomEye 検索 API の詳細については、 ZoomEye API v2 ドキュメントを参照してください。

はじめる

前提条件

ZoomEye APIキー
- ZoomEyeでアカウントを登録する
- アカウント設定からAPIキーを取得します
- APIキーはZoomEye APIへのリクエストを認証するために使用されます
Python環境
- Python 3.10以上が必要です
- あるいは、PythonをインストールせずにDockerを使用してサーバーを実行することもできます。

インストール

PIPの使用

あるいは、pip 経由でmcp-server-zoomeyeをインストールすることもできます。

pip install mcp-server-zoomeye

インストール後、次のコマンドを使用してスクリプトとして実行できます。

python -m mcp_server_zoomeye

Dockerの使用

Docker を使用して ZoomEye MCP サーバーを実行することもできます。

Docker Hubからプル

# Pull the latest image
docker pull zoomeyeteam/mcp-server-zoomeye:latest

# Run the container with your API key
docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:latest

注: linux/amd64およびlinux/arm64プラットフォームをサポートし、Intel/AMD および ARM (Apple Silicon など) プロセッサで実行できるマルチアーキテクチャ Docker イメージを提供します。

ソースからビルド

あるいは、ソースから Docker イメージをビルドすることもできます。

# Clone the repository
git clone https://github.com/zoomeye-ai/mcp_zoomeye.git
cd mcp_zoomeye

# Build the Docker image
docker build -t zoomeyeteam/mcp-server-zoomeye:local .

# Run the container
docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:local

UVの使用

uvはRustで書かれた高速なPythonパッケージインストーラー兼リゾルバーです。pipの現代的な代替手段であり、大幅なパフォーマンス向上を実現します。

UVの設置

# Install uv using curl (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using PowerShell (Windows)
irm https://astral.sh/uv/install.ps1 | iex

# Or using Homebrew (macOS)
brew install uv

uvx を使用して mcp-server-zoomeye を実行する

uvxを使用する場合、特別なインストールは必要ありません。これにより、Python パッケージを直接実行できます。

uvでインストール

あるいは、uv を使用してパッケージをインストールすることもできます。

# Install in the current environment
uv pip install mcp-server-zoomeye

# Or create and install in a new virtual environment
uv venv
uv pip install mcp-server-zoomeye

構成

環境変数

ZoomEye MCP サーバーには次の環境変数が必要です。

ZOOMEYE_API_KEY : 認証用のZoomEye APIキー

この環境変数はいくつかの方法で設定できます。

シェルセッションでエクスポートします:
export ZOOMEYE_API_KEY="your_api_key_here"
コンテナを実行するときに直接渡します(Docker の場合):
docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:latest

Claude.app を設定する

Claude 設定に以下を追加します。

"mcpServers": {
  "zoomeye": {
    "command": "uvx",
    "args": ["mcp-server-zoomeye"],
    "env": {
        "ZOOMEYE_API_KEY": "your_api_key_here"
    }
  }
}

"mcpServers": {
  "zoomeye": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "-e", "ZOOMEYE_API_KEY=your_api_key_here", "zoomeyeteam/mcp-server-zoomeye:latest"],
    "env": {
      "ZOOMEYE_API_KEY": "your_api_key_here"
    }
  }
}

"mcpServers": {
  "zoomeye": {
    "command": "python",
    "args": ["-m", "mcp_server_zoomeye"],
    "env": {
        "ZOOMEYE_API_KEY": "your_api_key_here"
    }
  }
}

Zed を設定する

Zed のsettings.jsonに以下を追加します。

"context_servers": [
  "mcp-server-zoomeye": {
    "command": "uvx",
    "args": ["mcp-server-zoomeye"],
    "env": {
        "ZOOMEYE_API_KEY": "your_api_key_here"
    }
  }
],

"context_servers": {
  "mcp-server-zoomeye": {
    "command": "python",
    "args": ["-m", "mcp_server_zoomeye"],
    "env": {
        "ZOOMEYE_API_KEY": "your_api_key_here"
    }
  }
},

やり取りの例

例1: グローバルApache Tomcatアセットを取得する

{
  "name": "zoomeye_search",
  "arguments": {
    "qbase64": "app=\"Apache Tomcat\""
  }
}

応答：

{
  "code": 60000,
  "message": "success",
  "total": 163139107,
  "query": "title=\"cisco vpn\"",
  "data": [
    {
      "url": "https://1.1.1.1:443",
      "ssl.jarm": "29d29d15d29d29d00029d29d29d29dea0f89a2e5fb09e4d8e099befed92cfa",
      "ssl.ja3s": "45094d08156d110d8ee97b204143db14",
      "iconhash_md5": "f3418a443e7d841097c714d69ec4bcb8",
      "robots_md5": "0b5ce08db7fb8fffe4e14d05588d49d9",
      "security_md5": "0b5ce08db7fb8fffe4e14d05588d49d9",
      "ip": "1.1.1.1",
      "domain": "www.google.com",
      "hostname": "SPACEX",
      "os": "windows",
      "port": 443,
      "service": "https",
      "title": ["GoogleGoogle appsGoogle Search"],
      "version": "1.1.0",
      "device": "webcam",
      "rdns": "c01031-001.cust.wallcloud.ch",
      "product": "OpenSSD",
      "header": "HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...",
      "header_hash": "27f9973fe57298c3b63919259877a84d",
      "body": "HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...",
      "body_hash": "84a18166fde3ee7e7c974b8d1e7e21b4",
      "banner": "SSH-2.0-OpenSSH_7.6p1 Ubuntu-4ubuntu0.3",
      "update_time": "2024-07-03T14:34:10",
      "header.server.name": "nginx",
      "header.server.version": "1.8.1",
      "continent.name": "Europe",
      "country.name": "Germany",
      "province.name": "Hesse",
      "city.name": "Frankfurt",
      "lon": "118.753262",
      "lat": "32.064838",
      "isp.name": "aviel.ru",
      "organization.name": "SERVISFIRST BANK",
      "zipcode": "210003",
      "idc": 0,
      "honeypot": 0,
      "asn": 4837,
      "protocol": "tcp",
      "ssl": "SSL Certificate Version: TLS 1.2 CipherSuit: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256...",
      "primary_industry": "Finance",
      "sub_industry": "bank",
      "rank": 60
    }
  ]
}

デバッグとトラブルシューティング

MCPインスペクターの使用

モデルコンテキストプロトコルインスペクターは、クライアントとのやり取りをシミュレートすることでMCPサーバーのデバッグを支援するツールです。ZoomEye MCPサーバーのテストに使用できます。

# For uvx installation
npx @modelcontextprotocol/inspector uvx mcp-server-zoomeye

# If developing locally
cd path/to/servers/src/mcp_server_zoomeye
npx @modelcontextprotocol/inspector uv run mcp-server-zoomeye

よくある問題

認証エラー
- ZoomEye APIキーが正しく、環境変数として適切に設定されていることを確認してください。
- APIキーの有効期限が切れていないか、取り消されていないか確認してください
接続の問題
- インターネット接続を確認してください
- ZoomEye API がダウンしていないか確認する
結果なし
- クエリが具体的すぎるか、構文エラーが含まれている可能性があります
- クエリを簡素化するか、別の検索語句を使用してみてください
レート制限
- ZoomEye API にはアカウントの種類に応じたレート制限があります
- リクエストの間隔をあけるか、アカウントをアップグレードして上限額を増やしましょう

高度な使用法

キャッシング

ZoomEye MCP サーバーは、パフォーマンスを向上させ、API 呼び出しを削減するためにキャッシュを実装します。

レスポンスはクエリパラメータに基づいてキャッシュされます
キャッシュ期間は設定可能（デフォルト: 1 時間）
クエリでignore_cache``trueに設定することでキャッシュをバイパスできます。

カスタムフィールド

fieldsパラメータを使用して、クエリ結果内の特定のフィールドをリクエストできます。

{
  "name": "zoomeye_search",
  "arguments": {
    "qbase64": "app=\"Apache\"",
    "fields": "ip,port,domain,service,os,country,city"
  }
}

ページネーション

多くの結果を返すクエリの場合は、ページ分けすることができます。

{
  "name": "zoomeye_search",
  "arguments": {
    "qbase64": "app=\"Apache\"",
    "page": 2,
    "pagesize": 20
  }
}

貢献

mcp-server-zoomeye の機能拡張と改善のため、皆様の貢献を歓迎いたします。新しい関連ツールの追加、既存機能の強化、ドキュメントの改善など、皆様からの貴重なご意見をお待ちしております。

他の MCP サーバーと実装パターンの例については、https: //github.com/modelcontextprotocol/serversを参照してください。

プルリクエストを歓迎します！mcp-server-zoomeye をより堅牢で実用的なものにするために、新しいアイデア、バグ修正、機能強化などをお気軽にご提供ください。

ライセンス

mcp-server-zoomeye は MIT ライセンスに基づきライセンスされています。つまり、MIT ライセンスの条件に従って、ソフトウェアを自由に使用、改変、配布できます。詳細については、プロジェクトリポジトリの LICENSE ファイルをご覧ください。

ZoomEye MCP Server

Integrations