urlDNA MCP Server

urlDNA MCP 服务器

Claude Prompt

urlDNA MCP Server 为 OpenAI GPT-4.1 和 Claude Desktop 等专注于安全的 LLM 代理提供了原生工具使用能力，通过 API 提供了与 urlDNA 威胁情报平台交互的直接接口。

安装与设置

本项目使用 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

以 SSE 模式运行 MCP 服务器：

uv run python urldna_mcp/server.py

开发

# 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/sse

该服务器可通过**服务器发送事件（SSE）**协议访问，支持 LLM 与后端工具之间的流式交互。

您可以直接将其与任何支持 MCP 规范的平台或 LLM（例如 Claude Desktop、OpenAI GPT-4.1）一起使用。

支持的工具

扫描

工具	描述
`fast_check`	即时检查 URL 是否已被扫描。返回 SAFE / MALICIOUS / UNRATED。
`new_scan`	提交 URL 进行完整扫描并等待结果（约 30-60 秒）。
`get_scan`	通过 ID 检索完整的扫描结果。

搜索

工具	描述
`search`	使用 CQL（自定义查询语言）跨域名、IP、技术、恶意标记等搜索扫描。支持分页（第 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",
        "run.py"
      ],
      "env": {
        "x-api-key": "<urlDNA_API_KEY>"
      }
    }
  }
}

将 <YOUR_PATH> 替换为项目目录的实际路径，并将 <urlDNA_API_KEY> 替换为您从 https://urldna.io 获取的 API 密钥。

配置完成后，您可以使用自然语言提示 Claude，例如：

“在 urlDNA 中搜索标题类似 paypal 的恶意扫描”

“为来自意大利且被标记为恶意的移动扫描创建一个已保存的查询”

“显示与 Google 品牌关联的所有扫描”

Claude 将自动调用正确的工具并从 urlDNA 平台返回结果。

将 MCP 服务器与 OpenAI GPT-4.1 一起使用

from openai import OpenAI

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

response = client.responses.create(
    model="gpt-4.1",  # GPT-4.1 supports native MCP tool use
    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"}]
        }
    ],
    text={"format": {"type": "text"}},
    reasoning={},
    tools=[
        {
            "type": "mcp",
            "server_label": "urlDNA",
            "server_url": "https://mcp.urldna.io/sse",
            "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)

                # --- 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)

容器部署

使用 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

贡献

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

联系与支持

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

文档