urlDNA

urlDNA MCP Server

Blog

Der urlDNA MCP Server ermöglicht die native Nutzung von Tools für sicherheitsfokussierte LLM-Agenten wie OpenAI GPT, Google Gemini und Claude Desktop und bietet eine direkte Schnittstelle zur Interaktion mit der urlDNA Threat-Intelligence-Plattform über die API.

Das Repository stellt denselben Tool-Satz über zwei Transportwege bereit:

• stdio für lokale Desktop-Integrationen wie Claude Desktop.
• streamable-http für gehostete Bereitstellungen wie Cloud Run.

---

Installation & Einrichtung

Dieses Projekt verwendet uv für schnelles Python-Paketmanagement.

Voraussetzungen

Installieren Sie uv, falls Sie es noch nicht haben:

# 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

Schnellstart

1. Projekt klonen und einrichten:

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

2. MCP-Server lokal ausführen (Stdio-Modus):

uv run python urldna_mcp/run.py

3. MCP-Server im streamable HTTP-Modus ausführen:

uv run python urldna_mcp/server.py

Der gehostete Server liest diese Umgebungsvariablen:

• PORT: HTTP-Port, an den gebunden wird. Standard: 8080.
• MCP_PATH: Öffentlicher MCP-Endpunktpfad. Standard: /.

Entwicklung

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

---

Gehosteter MCP-Server

Der urlDNA MCP-Server ist bereits gehostet und verfügbar unter:

https://mcp.urldna.io/

Dieser Server ist über streamable HTTP erreichbar, was ihn für Cloud Run und andere anfragegesteuerte Plattformen geeignet macht.

Sie können ihn direkt mit jeder Plattform oder jedem LLM verwenden, das die MCP-Spezifikation unterstützt (z. B. Claude Desktop, OpenAI GPT, Google Gemini).

---

Unterstützte Tools

Scannen

Tool	Beschreibung
fast_check	Sofort prüfen, ob eine URL gescannt wurde. Gibt SAFE / MALICIOUS / UNRATED zurück.
new_scan	Eine URL für einen vollständigen Scan einreichen und auf das Ergebnis warten (~30–60s).
get_scan	Ein vollständiges Scan-Ergebnis anhand der ID abrufen.

Suche

Tool	Beschreibung
search	Scans mit CQL (Custom Query Language) über Domain, IP, Technologie, Malicious-Flag und mehr durchsuchen. Unterstützt AND- und OR-Ausdrücke sowie Paginierung (Seite 2+ erfordert PREMIUM).

Gespeicherte Abfragen

Tool	Beschreibung
list_queries	Alle gespeicherten Abfragen für den authentifizierten Benutzer auflisten.
get_query	Eine bestimmte gespeicherte Abfrage und ihre Filter anhand der ID abrufen.
create_query	Eine neue gespeicherte Abfrage mit einer oder mehreren CQL-Filterbedingungen erstellen.
update_query	Name und Filter einer vorhandenen Abfrage aktualisieren (vollständige Ersetzung).
delete_query	Eine gespeicherte Abfrage dauerhaft anhand der ID löschen.
query_scans	Alle passenden Scans für eine gespeicherte Abfrage abrufen.

Markenüberwachung

Tool	Beschreibung
list_brands	Verfügbare Marken mit optionaler Namenssuche und Sichtbarkeitsfilter auflisten (ALL / FREE / PREMIUM / USER_BRANDS).
get_brand	Vollständige Details einer bestimmten Marke anhand der ID abrufen.
brand_scans	Alle mit einer Marke verbundenen Scans abrufen. Unterstützt zusätzliche CQL-Filterung.

API-Referenz

Tool	Beschreibung
search_docs	Die vollständige urlDNA OpenAPI- und Dokumentation abrufen.

---

Integration mit Claude Desktop

Um den urlDNA MCP server in Claude Desktop zu integrieren, aktualisieren Sie Ihre 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>"
      }
    }
  }
}

Ersetzen Sie <YOUR_PATH> durch das übergeordnete Verzeichnis, das dieses Repository enthält, und <urlDNA_API_KEY> durch Ihren API-Schlüssel von https://urldna.io.

Für gehostete MCP-Clients verweisen Sie diese auf https://mcp.urldna.io/ oder Ihre eigene bereitgestellte MCP_PATH.

Nach der Konfiguration können Sie Claude in natürlicher Sprache auffordern, zum Beispiel:

"Suche in urlDNA nach bösartigen Scans mit Titel wie paypal"

"Erstelle eine gespeicherte Abfrage für mobile Scans aus Italien, die als bösartig markiert sind"

"Zeig mir alle Scans, die mit der Marke Google verbunden sind"

Claude ruft automatisch das richtige Tool auf und gibt Ergebnisse von der urlDNA-Plattform zurück.

---

Verwenden des MCP-Servers mit OpenAI GPT

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)

---

Verwenden des MCP-Servers mit Google Gemini

Gemini verbindet sich mit dem urlDNA MCP-Server über fastmcp, und Tools werden automatisch erkannt, anstatt als allowed_tools-Liste übergeben zu werden.

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

---

Container-Bereitstellung

Mit Docker bauen und ausführen:

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

Suchsyntax

Die search- und brand_scans-Tools leiten das bereitgestellte CQL direkt an die urlDNA-API weiter. Sie können Bedingungen entweder mit AND oder OR kombinieren.

Beispiele:

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

---

Mitwirken

1. Repository forken
2. Feature-Branch erstellen: git checkout -b feature-name
3. Entwicklungsabhängigkeiten installieren: uv sync --dev
4. Änderungen vornehmen und sicherstellen, dass Tests bestehen
5. Code formatieren: uv run black .
6. Pull-Request einreichen

---

Kontakt & Support

Für Support oder API-Zugriff besuchen Sie https://urldna.io oder senden Sie eine E-Mail an urldna@urldna.io.