urlDNA MCP Server

officiel

Analyser et examiner dynamiquement les URL potentiellement malveillantes à l'aide de urlDNA.io

Documentation

Serveur MCP urlDNA

Claude Prompt

Le urlDNA MCP Server permet l'utilisation native d'outils pour les agents LLM axés sur la sécurité comme OpenAI GPT-4.1 et Claude Desktop, offrant une interface directe pour interagir avec la plateforme de renseignement sur les menaces urlDNA via l'API.

Installation et configuration

Ce projet utilise uv pour une gestion rapide des paquets Python.

Prérequis

Installez uv si ce n'est pas déjà fait :

# 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

Démarrage rapide

Cloner et configurer le projet :

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

Exécuter le serveur MCP localement (mode stdio) :

uv run python urldna_mcp/run.py

Exécuter le serveur MCP en mode SSE :

uv run python urldna_mcp/server.py

Développement

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

Serveur MCP hébergé

Le serveur urlDNA MCP est déjà hébergé et disponible à l'adresse :

https://mcp.urldna.io/sse

Ce serveur est accessible via le protocole Server-Sent Events (SSE), qui prend en charge les interactions en streaming entre les LLM et les outils backend.

Vous pouvez l'utiliser directement avec n'importe quelle plateforme ou LLM prenant en charge la spécification MCP (par exemple, Claude Desktop, OpenAI GPT-4.1).

Outils pris en charge

Analyse

Outil	Description
`fast_check`	Vérifier instantanément si une URL a été analysée. Renvoie SAFE / MALICIOUS / UNRATED.
`new_scan`	Soumettre une URL pour une analyse complète et attendre le résultat (~30–60s).
`get_scan`	Récupérer un résultat d'analyse complet par ID.

Recherche

Outil	Description
`search`	Rechercher des analyses en utilisant CQL (Custom Query Language) sur le domaine, l'IP, la technologie, le drapeau malveillant, etc. Prend en charge la pagination (page 2+ nécessite PREMIUM).

Requêtes sauvegardées

Outil	Description
`list_queries`	Lister toutes les requêtes sauvegardées pour l'utilisateur authentifié.
`get_query`	Récupérer une requête sauvegardée spécifique et ses filtres par ID.
`create_query`	Créer une nouvelle requête sauvegardée avec une ou plusieurs conditions de filtre CQL.
`update_query`	Mettre à jour le nom et les filtres d'une requête existante (remplacement complet).
`delete_query`	Supprimer définitivement une requête sauvegardée par ID.
`query_scans`	Récupérer toutes les analyses correspondantes pour une requête sauvegardée.

Surveillance de marque

Outil	Description
`list_brands`	Lister les marques disponibles avec recherche optionnelle par nom et filtre de visibilité (ALL / FREE / PREMIUM / USER_BRANDS).
`get_brand`	Récupérer les détails complets d'une marque spécifique par ID.
`brand_scans`	Obtenir toutes les analyses associées à une marque. Prend en charge le filtrage CQL supplémentaire.

Référence API

Outil	Description
`search_docs`	Récupérer l'OpenAPI complète d'urlDNA et les documentations.

Intégration avec Claude Desktop

Pour intégrer le urlDNA MCP server dans Claude Desktop, mettez à jour votre claude_desktop_config.json :

{
  "mcpServers": {
    "urlDNA": {
      "command": "uv",
      "args": [
        "--directory",
        "<YOUR_PATH>\\urldna_mcp",
        "run",
        "run.py"
      ],
      "env": {
        "x-api-key": "<urlDNA_API_KEY>"
      }
    }
  }
}

Remplacez <YOUR_PATH> par le chemin réel vers le répertoire du projet et <urlDNA_API_KEY> par votre clé API de https://urldna.io.

Une fois configuré, vous pouvez interagir avec Claude en langage naturel, par exemple :

"Rechercher dans urlDNA les analyses malveillantes avec un titre comme paypal"

"Créer une requête sauvegardée pour les analyses mobiles depuis l'Italie qui sont signalées comme malveillantes"

"Afficher toutes les analyses associées à la marque Google"

Claude appellera automatiquement le bon outil et renverra les résultats de la plateforme urlDNA.

Utilisation du serveur MCP avec 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)

Déploiement conteneurisé

Construire et exécuter avec 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

Contribuer

Forker le dépôt
Créer une branche de fonctionnalité : git checkout -b feature-name
Installer les dépendances de développement : uv sync --dev
Apporter vos modifications et s'assurer que les tests passent
Formater le code : uv run black .
Soumettre une pull request

Contact et support

Pour du support ou un accès API, visitez https://urldna.io ou envoyez un email à [email protected].