urlDNA

officiel

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

GitHub

Que pouvez-vous faire avec urlDNA MCP ?

Vérification instantanée de la sécurité d’une URL — Demandez de vérifier rapidement si une URL est SÛRE, MALVEILLANTE ou NON ÉVALUÉE à l’aide de fast_check.
Analyse complète d’URL — Soumettez une URL pour une analyse exhaustive avec new_scan et récupérez les résultats par ID via get_scan.
Recherche de menaces basée sur CQL — Recherchez des analyses sur des domaines, des IP, des technologies et des indicateurs malveillants à l’aide de search avec des expressions ET/OU.
Gestion des requêtes enregistrées — Créez, listez, mettez à jour et supprimez des filtres CQL réutilisables avec create_query, list_queries, update_query et delete_query.
Surveillance de marque — Listez les marques, récupérez les détails et obtenez les analyses associées à l’aide de list_brands, get_brand et brand_scans.
Consultation de la documentation API — Récupérez la documentation OpenAPI complète d’urlDNA directement avec search_docs.

Documentation

Serveur MCP urlDNA

Blog

Claude Prompt

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

Le dépôt expose le même ensemble d'outils sur deux transports :

stdio pour les intégrations de bureau locales comme Claude Desktop.
streamable-http pour les déploiements hébergés comme Cloud Run.

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

Clonez et configurez le projet :

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

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

uv run python urldna_mcp/run.py

Exécutez le serveur MCP en mode HTTP streamable :

uv run python urldna_mcp/server.py

Le serveur hébergé lit ces variables d'environnement :

PORT : port HTTP à utiliser. Par défaut 8080.
MCP_PATH : chemin public du point de terminaison MCP. Par défaut /.

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/

Ce serveur est accessible via HTTP streamable, ce qui le rend adapté à Cloud Run et à d'autres plateformes pilotées par requêtes.

Vous pouvez l'utiliser directement avec toute plateforme ou LLM prenant en charge la spécification MCP (par exemple, Claude Desktop, OpenAI GPT, Google Gemini).

Outils pris en charge

Analyse

Outil	Description
`fast_check`	Vérifiez instantanément si une URL a été analysée. Renvoie SÛR / MALVEILLANT / NON ÉVALUÉ.
`new_scan`	Soumettez une URL pour une analyse complète et attendez le résultat (~30–60 s).
`get_scan`	Récupérez un résultat d'analyse complet par ID.

Recherche

Outil	Description
`search`	Recherchez des analyses à l'aide de CQL (Custom Query Language) sur le domaine, l'IP, la technologie, le drapeau malveillant, et plus encore. Prend en charge les expressions `AND` et `OR` ainsi que la pagination (page 2+ nécessite PREMIUM).

Requêtes enregistrées

Outil	Description
`list_queries`	Listez toutes les requêtes enregistrées pour l'utilisateur authentifié.
`get_query`	Récupérez une requête enregistrée spécifique et ses filtres par ID.
`create_query`	Créez une nouvelle requête enregistrée avec une ou plusieurs conditions de filtre CQL.
`update_query`	Mettez à jour le nom et les filtres d'une requête existante (remplacement complet).
`delete_query`	Supprimez définitivement une requête enregistrée par ID.
`query_scans`	Récupérez toutes les analyses correspondant à une requête enregistrée.

Surveillance de marque

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

Référence API

Outil	Description
`search_docs`	Récupérez l'intégralité de l'OpenAPI 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",
        "urldna_mcp\\run.py"
      ],
      "env": {
        "x-api-key": "<urlDNA_API_KEY>"
      }
    }
  }
}

Remplacez <YOUR_PATH> par le répertoire parent contenant ce dépôt et <urlDNA_API_KEY> par votre clé API depuis https://urldna.io.

Pour les clients MCP hébergés, pointez-les vers https://mcp.urldna.io/ ou votre propre MCP_PATH déployé.

Une fois configuré, vous pouvez demander à Claude en langage naturel, par exemple :

« Recherchez dans urlDNA les analyses malveillantes avec un titre contenant paypal »

« Créez une requête enregistrée pour les analyses mobiles provenant d'Italie signalées comme malveillantes »

« Montrez-moi 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

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)

Utilisation du serveur MCP avec Google Gemini

Gemini se connecte au serveur urlDNA MCP via fastmcp, et les outils sont découverts automatiquement plutôt que transmis sous forme de liste 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())

Déploiement en conteneur

Construisez et exécutez 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

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

Syntaxe de recherche

Les outils search et brand_scans transmettent directement le CQL fourni à l'API urlDNA. Vous pouvez combiner des conditions avec AND ou OR.

Exemples :

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

Contribution

Forkez le dépôt
Créez une branche de fonctionnalité : git checkout -b feature-name
Installez les dépendances de développement : uv sync --dev
Apportez vos modifications et assurez-vous que les tests passent
Formatez le code : uv run black .
Soumettez une demande d'extraction (pull request)

Contact et support

Pour le support ou l'accès à l'API, visitez https://urldna.io ou envoyez un e-mail à urldna@urldna.io.