urlDNA

urlDNA MCP サーバー

ブログ

urlDNA MCP Server を使用すると、OpenAI GPT、Google Gemini、Claude Desktop などのセキュリティに特化した LLM エージェントがネイティブにツールを利用できます。API 経由で urlDNA の脅威インテリジェンスプラットフォームと直接やり取りするためのインターフェースを提供します。

このリポジトリでは、2 種類のトランスポートで同じツールセットを利用できます。

• stdio：Claude Desktop などのローカルデスクトップ統合向けです。
• streamable-http：Cloud Run などのホスティング環境向けです。

---

インストールとセットアップ

このプロジェクトでは、高速な Python パッケージ管理に uv を使用しています。

前提条件

まだインストールしていない場合は、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. MCP サーバーを streamable HTTP モードで実行します。

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	1 つ以上の 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

---

コントリビュート

1. リポジトリをフォークします
2. 機能ブランチを作成します：git checkout -b feature-name
3. 開発用の依存関係をインストールします：uv sync --dev
4. 変更を加え、テストが通ることを確認します
5. コードをフォーマットします：uv run black .
6. プルリクエストを送信します

---

お問い合わせとサポート

サポートまたはAPIへのアクセスについては、https://urldna.io をご覧いただくか、[email protected] までメールでお問い合わせください。