urlDNA

官方

使用 urlDNA.io 動態掃描並分析潛在的惡意網址。

GitHub

你可以用 urlDNA MCP 做什麼？

即時 URL 安全檢查 — 使用 fast_check 快速確認 URL 是否為 SAFE、MALICIOUS 或 UNRATED。
完整 URL 掃描 — 使用 new_scan 提交 URL 進行全面掃描，並透過 get_scan 依 ID 取得結果。
基於 CQL 的威脅搜尋 — 使用 search 搭配 AND/OR 表達式，跨網域、IP、技術及惡意旗標搜尋掃描結果。
已儲存查詢管理 — 使用 create_query、list_queries、update_query 和 delete_query 建立、列出、更新及刪除可重複使用的 CQL 篩選器。
品牌監控 — 使用 list_brands、get_brand 和 brand_scans 列出品牌、取得詳細資訊並擷取相關掃描。
API 文件查詢 — 使用 search_docs 直接取得完整的 urlDNA OpenAPI 文件。

文件

urlDNA MCP 伺服器

部落格

Claude Prompt

urlDNA MCP Server 讓安全導向的 LLM 代理（如 OpenAI GPT、Google Gemini 和 Claude Desktop）能原生使用工具，透過 API 提供與 urlDNA 威脅情報平台的直接介面。

此儲存庫透過兩種傳輸方式暴露相同的工具集：

stdio 用於本機桌面整合，例如 Claude Desktop。
streamable-http 用於託管部署，例如 Cloud Run。

安裝與設定

此專案使用 uv 進行快速的 Python 套件管理。

前置需求

如果您尚未安裝 uv，請先安裝：

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip
pip install uv

快速開始

複製並設定專案：

git clone <repository-url>
cd urlDNA-mcp-server
uv sync

在本機執行 MCP 伺服器（stdio 模式）：

uv run python urldna_mcp/run.py

以可串流 HTTP 模式執行 MCP 伺服器：

uv run python urldna_mcp/server.py

託管伺服器會讀取以下環境變數：

PORT：要綁定的 HTTP 連接埠。預設為 8080。
MCP_PATH：公開的 MCP 端點路徑。預設為 /。

開發

# Install development dependencies
uv sync --dev

# Run tests (when available)
uv run pytest

# Format code
uv run black .

# Type checking
uv run mypy .

# Lint code
uv run flake8 .

託管 MCP 伺服器

urlDNA MCP 伺服器已託管並可供使用，位於：

https://mcp.urldna.io/

此伺服器可透過可串流 HTTP 存取，因此適合 Cloud Run 和其他請求驅動的平台。

您可以直接搭配任何支援 MCP 規範的平台或 LLM 使用（例如 Claude Desktop、OpenAI GPT、Google Gemini）。

支援的工具

掃描

工具	說明
`fast_check`	立即檢查 URL 是否已被掃描。回傳 SAFE / MALICIOUS / UNRATED。
`new_scan`	提交 URL 進行完整掃描並等待結果（約 30–60 秒）。
`get_scan`	依 ID 擷取完整的掃描結果。

搜尋

工具	說明
`search`	使用 CQL（自訂查詢語言）跨網域、IP、技術、惡意標記等搜尋掃描。支援 `AND` 和 `OR` 表達式以及分頁（第 2 頁起需要 PREMIUM）。

已儲存查詢

工具	說明
`list_queries`	列出已驗證使用者的所有已儲存查詢。
`get_query`	依 ID 擷取特定已儲存查詢及其篩選條件。
`create_query`	使用一個或多個 CQL 篩選條件建立新的已儲存查詢。
`update_query`	更新既有查詢的名稱和篩選條件（完整取代）。
`delete_query`	依 ID 永久刪除已儲存查詢。
`query_scans`	擷取已儲存查詢的所有相符掃描。

品牌監控

工具	說明
`list_brands`	列出可用品牌，可選擇名稱搜尋和可見性篩選（ALL / FREE / PREMIUM / USER_BRANDS）。
`get_brand`	依 ID 擷取特定品牌的完整詳細資料。
`brand_scans`	取得與品牌相關的所有掃描。支援額外的 CQL 篩選。

API 參考

工具	說明
`search_docs`	擷取完整的 urlDNA OpenAPI 和文件。

與 Claude Desktop 整合

若要將 urlDNA MCP server 整合到 Claude Desktop，請更新您的 claude_desktop_config.json：

{
  "mcpServers": {
    "urlDNA": {
      "command": "uv",
      "args": [
        "--directory",
        "<YOUR_PATH>\\urldna_mcp",
        "run",
        "urldna_mcp\\run.py"
      ],
      "env": {
        "x-api-key": "<urlDNA_API_KEY>"
      }
    }
  }
}

將 <YOUR_PATH> 取代為包含此儲存庫的父目錄，並將 <urlDNA_API_KEY> 取代為您從 https://urldna.io 取得的 API 金鑰。

對於託管的 MCP 用戶端，請將它們指向 https://mcp.urldna.io/ 或您自行部署的 MCP_PATH。

設定完成後，您可以用自然語言提示 Claude，例如：

「在 urlDNA 中搜尋標題類似 paypal 的惡意掃描」

「建立一個來自義大利且被標記為惡意的手機掃描已儲存查詢」

「顯示與 Google 品牌相關的所有掃描」

Claude 會自動呼叫正確的工具，並從 urlDNA 平台回傳結果。

搭配 OpenAI GPT 使用 MCP 伺服器

from openai import OpenAI

# Initialize OpenAI client (assumes OPENAI_API_KEY is set via environment variable)
client = OpenAI()

response = client.responses.create(
    model="gpt-3.5-turbo",  # Note: MCP tool use requires a Responses API-compatible model
    input=[
        {
            "role": "system",
            "content": [{"type": "input_text", "text": "You are a cybersecurity analyst using urlDNA."}]
        },
        {
            "role": "user",
          "content": [{"type": "input_text", "text": "Search in urlDNA for malicious scans with title like paypal or login"}]
        }
    ],
    text={"format": {"type": "text"}},
    reasoning={},
    tools=[
        {
            "type": "mcp",
            "server_label": "urlDNA",
            "server_url": "https://mcp.urldna.io/",
            "headers": {
                "x-api-key": "<URLDNA_API_KEY>"  # Replace with your urlDNA API key
            },
            "allowed_tools": [
                # --- Scanning ---
                "new_scan",       # Submit a URL for a full scan and wait for the result
                "get_scan",       # Retrieve a scan result by ID
                "fast_check",     # Lightweight instant safety check (SAFE / MALICIOUS / UNRATED)

                # --- Search ---
                "search",         # Search scans using CQL (Custom Query Language, AND/OR supported)

                # --- Saved Queries (PREMIUM) ---
                "list_queries",
                "get_query",
                "create_query",
                "update_query",
                "delete_query",
                "query_scans",

                # --- Brand Monitoring (PREMIUM) ---
                "list_brands",
                "get_brand",
                "brand_scans",

                # --- API Reference ---
                "search_docs",
            ],
            "require_approval": "never"
        }
    ],
    temperature=0.7,
    top_p=1,
    max_output_tokens=2048,
    store=True
)

print(response.output)

搭配 Google Gemini 使用 MCP 伺服器

Gemini 透過 fastmcp 連線到 urlDNA MCP 伺服器，工具會自動探索，而非以 allowed_tools 清單傳遞。

import os
import asyncio
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport
from google import genai

async def main():
    # 1. Connect FastMCP client directly to streamable-http
    transport = StreamableHttpTransport(
        "https://mcp.urldna.io/",
        headers={"x-api-key": os.getenv("URLDNA_API_KEY", "YOUR_KEY")},
    )
    client_mcp = Client(transport)

    async with client_mcp:
        ai = genai.Client(vertexai=True, project=os.getenv("GOOGLE_CLOUD_PROJECT", "YOUR_PROJECT_ID"))
        response = await ai.aio.models.generate_content(
            model="gemini-2.5-flash",
            contents="Search in urlDNA for malicious scans with title like paypal",
            # Pass the live MCP session (not just tool declarations) so Gemini
            # can automatically call tools and receive their results.
            config=genai.types.GenerateContentConfig(tools=[client_mcp.session]),
        )

        print(response.text)


if __name__ == "__main__":
    asyncio.run(main())

容器部署

使用 Docker 建置和執行：

# Build the container
docker build -t urldna-mcp-server .

# Run the server
docker run -p 8080:8080 -e x-api-key=<URLDNA_API_KEY> urldna-mcp-server

# Optional: override the public MCP path if you do not want /
docker run -p 8080:8080 -e MCP_PATH=/custom-path -e x-api-key=<URLDNA_API_KEY> urldna-mcp-server

# Cloud Run example
gcloud run deploy urldna-mcp-server \
  --source . \
  --allow-unauthenticated \
  --set-env-vars MCP_PATH=/

搜尋語法

search 和 brand_scans 工具會將提供的 CQL 直接轉發到 urlDNA API。您可以使用 AND 或 OR 組合條件。

範例：

malicious = true AND technology LIKE wordpress
domain = google.com OR domain = youtube.com
(domain = paypal.com OR title LIKE paypal) AND country_code = IT

貢獻

Fork 此儲存庫
建立功能分支：git checkout -b feature-name
安裝開發依賴項：uv sync --dev
進行變更並確保測試通過
格式化程式碼：uv run black .
提交 Pull Request

聯絡與支援

如需支援或 API 存取，請造訪 https://urldna.io 或寄送電子郵件至 urldna@urldna.io。