urlDNA MCP Server

offiziell

Dynamisch potenziell schädliche URLs scannen und analysieren mit der urlDNA.io

Dokumentation

urlDNA MCP Server

Claude Prompt

Der urlDNA MCP Server ermöglicht die native Werkzeugnutzung für sicherheitsorientierte LLM-Agenten wie OpenAI GPT-4.1 und Claude Desktop und bietet eine direkte Schnittstelle zur Interaktion mit der urlDNA Threat-Intelligence-Plattform per API.

Installation & Einrichtung

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

Voraussetzungen

Installieren Sie uv, falls noch nicht geschehen:

# 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

Projekt klonen und einrichten:

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

MCP-Server lokal ausführen (stdio-Modus):

uv run python urldna_mcp/run.py

MCP-Server im SSE-Modus ausführen:

uv run python urldna_mcp/server.py

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

Dieser Server ist über das Server-Sent Events (SSE)-Protokoll erreichbar, das Streaming-Interaktionen zwischen LLMs und den Backend-Werkzeugen unterstützt.

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

Unterstützte Werkzeuge

Scannen

Werkzeug	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–60 s).
`get_scan`	Ein vollständiges Scan-Ergebnis anhand der ID abrufen.

Suche

Werkzeug	Beschreibung
`search`	Scans mit CQL (Custom Query Language) nach Domain, IP, Technologie, Malicious-Flag und mehr durchsuchen. Unterstützt Paginierung (Seite 2+ erfordert PREMIUM).

Gespeicherte Abfragen

Werkzeug	Beschreibung
`list_queries`	Alle gespeicherten Abfragen des authentifizierten Benutzers auflisten.
`get_query`	Eine bestimmte gespeicherte Abfrage und deren Filter anhand der ID abrufen.
`create_query`	Eine neue gespeicherte Abfrage mit einer oder mehreren CQL-Filterbedingungen erstellen.
`update_query`	Name und Filter einer bestehenden Abfrage aktualisieren (vollständiger Ersatz).
`delete_query`	Eine gespeicherte Abfrage dauerhaft anhand der ID löschen.
`query_scans`	Alle übereinstimmenden Scans für eine gespeicherte Abfrage abrufen.

Markenüberwachung

Werkzeug	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 verknüpften Scans abrufen. Unterstützt zusätzliche CQL-Filterung.

API-Referenz

Werkzeug	Beschreibung
`search_docs`	Die vollständige urlDNA OpenAPI und Dokumentationen 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",
        "run.py"
      ],
      "env": {
        "x-api-key": "<urlDNA_API_KEY>"
      }
    }
  }
}

Ersetzen Sie <YOUR_PATH> durch den tatsächlichen Pfad zum Projektverzeichnis und <urlDNA_API_KEY> durch Ihren API-Schlüssel von https://urldna.io.

Nach der Konfiguration können Sie Claude mit natürlicher Sprache anweisen, 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 gekennzeichnet sind"

"Zeige mir alle Scans, die mit der Marke Google verknüpft sind"

Claude wird automatisch das richtige Werkzeug aufrufen und Ergebnisse von der urlDNA-Plattform zurückgeben.

Verwendung des MCP-Servers mit 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)

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

Mitwirken

Repository forken
Feature-Branch erstellen: git checkout -b feature-name
Entwicklungsabhängigkeiten installieren: uv sync --dev
Änderungen vornehmen und sicherstellen, dass Tests bestanden werden
Code formatieren: uv run black .
Pull-Request einreichen

Kontakt & Support

Für Support oder API-Zugang besuchen Sie https://urldna.io oder senden Sie eine E-Mail an [email protected].