urlDNA MCP Server

oficial

Digitalize e analise dinamicamente URLs potencialmente maliciosas usando o urlDNA.io

Documentação

Servidor MCP urlDNA

Claude Prompt

O urlDNA MCP Server permite o uso nativo de ferramentas para agentes LLM focados em segurança, como OpenAI GPT-4.1 e Claude Desktop, fornecendo uma interface direta para interagir com a plataforma de inteligência de ameaças urlDNA via API.

Instalação e Configuração

Este projeto usa uv para gerenciamento rápido de pacotes Python.

Pré-requisitos

Instale o uv caso ainda não o tenha:

# 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

Início Rápido

Clone e configure o projeto:

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

Execute o servidor MCP localmente (modo stdio):

uv run python urldna_mcp/run.py

Execute o servidor MCP em modo SSE:

uv run python urldna_mcp/server.py

Desenvolvimento

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

Servidor MCP Hospedado

O servidor urlDNA MCP já está hospedado e disponível em:

https://mcp.urldna.io/sse

Este servidor é acessível via protocolo Server-Sent Events (SSE), que suporta interações de streaming entre LLMs e as ferramentas de backend.

Você pode usá-lo diretamente com qualquer plataforma ou LLM que suporte a especificação MCP (ex.: Claude Desktop, OpenAI GPT-4.1).

Ferramentas Suportadas

Varredura

Ferramenta	Descrição
`fast_check`	Verifica instantaneamente se uma URL foi analisada. Retorna SEGURO / MALICIOSO / NÃO CLASSIFICADO.
`new_scan`	Envia uma URL para varredura completa e aguarda o resultado (~30–60s).
`get_scan`	Recupera um resultado completo de varredura pelo ID.

Pesquisa

Ferramenta	Descrição
`search`	Pesquisa varreduras usando CQL (Custom Query Language) por domínio, IP, tecnologia, flag de malicioso e mais. Suporta paginação (página 2+ requer PREMIUM).

Consultas Salvas

Ferramenta	Descrição
`list_queries`	Lista todas as consultas salvas do usuário autenticado.
`get_query`	Recupera uma consulta salva específica e seus filtros pelo ID.
`create_query`	Cria uma nova consulta salva com uma ou mais condições de filtro CQL.
`update_query`	Atualiza o nome e filtros de uma consulta existente (substituição completa).
`delete_query`	Exclui permanentemente uma consulta salva pelo ID.
`query_scans`	Recupera todas as varreduras correspondentes a uma consulta salva.

Monitoramento de Marca

Ferramenta	Descrição
`list_brands`	Lista marcas disponíveis com busca opcional por nome e filtro de visibilidade (TODAS / GRATUITAS / PREMIUM / MARCAS_DO_USUÁRIO).
`get_brand`	Recupera detalhes completos de uma marca específica pelo ID.
`brand_scans`	Obtém todas as varreduras associadas a uma marca. Suporta filtragem adicional com CQL.

Referência da API

Ferramenta	Descrição
`search_docs`	Busca a OpenAPI completa do urlDNA e documentações.

Integração com Claude Desktop

Para integrar o urlDNA MCP server no Claude Desktop, atualize seu claude_desktop_config.json:

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

Substitua <YOUR_PATH> pelo caminho real do diretório do projeto e <urlDNA_API_KEY> pela sua chave de API do https://urldna.io.

Uma vez configurado, você pode solicitar ao Claude com linguagem natural, por exemplo:

"Pesquise no urlDNA por varreduras maliciosas com título semelhante a paypal"

"Crie uma consulta salva para varreduras mobile da Itália que estejam sinalizadas como maliciosas"

"Mostre-me todas as varreduras associadas à marca Google"

O Claude chamará automaticamente a ferramenta correta e retornará os resultados da plataforma urlDNA.

Usando o Servidor MCP com 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)

Implantação com Contêiner

Construa e execute com 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

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade: git checkout -b feature-name
Instale as dependências de desenvolvimento: uv sync --dev
Faça suas alterações e garanta que os testes passem
Formate o código: uv run black .
Envie um pull request

Contato e Suporte

Para suporte ou acesso à API, visite https://urldna.io ou envie um e-mail para [email protected].