urlDNA

urlDNA MCP 服务器

博客

urlDNA MCP Server 为 OpenAI GPT、Google Gemini 和 Claude Desktop 等专注于安全的大模型 Agent 提供原生工具调用能力，让它们可以通过 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

快速开始

1. 克隆并设置项目：

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

2. 在本地运行 MCP 服务（stdio 模式）：

uv run python urldna_mcp/run.py

3. 以 streamable 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/

此服务通过 streamable HTTP 提供访问，因此适用于 Cloud Run 和其他由请求驱动的平台。

你可以直接将其用于任何支持 MCP 规范的平台或大模型（例如 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 集成

若要在 Claude Desktop 中集成 urlDNA MCP server，请更新 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

---

参与贡献

1. Fork 此代码仓库
2. 创建功能分支：git checkout -b feature-name
3. 安装开发依赖项：uv sync --dev
4. 进行更改并确保测试通过
5. 格式化代码：uv run black .
6. 提交拉取请求

---

联系与支持

如需支持或 API 访问权限，请访问 https://urldna.io，或发送邮件至 [email protected]。