urlDNA

urlDNA MCP Sunucusu

Blog

urlDNA MCP Server, OpenAI GPT, Google Gemini ve Claude Desktop gibi güvenlik odaklı LLM ajanları için yerel araç kullanımını sağlar ve urlDNA tehdit istihbarat platformuyla API üzerinden doğrudan etkileşim için bir arayüz sunar.

Depo, aynı araç setini iki taşıma protokolü üzerinden sunar:

• Yerel masaüstü entegrasyonları (Claude Desktop gibi) için stdio.
• Cloud Run gibi barındırılan dağıtımlar için streamable-http.

---

Kurulum ve Yapılandırma

Bu proje, hızlı Python paket yönetimi için uv kullanır.

Ön Koşullar

Henüz yapmadıysanız uv'yi kurun:

# 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

Hızlı Başlangıç

1. Projeyi klonlayın ve kurun:

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

2. MCP sunucusunu yerel olarak çalıştırın (stdio modu):

uv run python urldna_mcp/run.py

3. MCP sunucusunu akışkan HTTP modunda çalıştırın:

uv run python urldna_mcp/server.py

Barındırılan sunucu şu ortam değişkenlerini okur:

• PORT: Bağlanacak HTTP portu. Varsayılan 8080.
• MCP_PATH: Genel MCP uç nokta yolu. Varsayılan /.

Geliştirme

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

---

Barındırılan MCP Sunucusu

urlDNA MCP sunucusu zaten barındırılıyor ve kullanılabilir:

https://mcp.urldna.io/

Bu sunucuya akışkan HTTP üzerinden erişilebilir; bu da onu Cloud Run ve diğer istek odaklı platformlar için uygun hale getirir.

MCP spesifikasyonunu destekleyen herhangi bir platform veya LLM ile doğrudan kullanabilirsiniz (ör. Claude Desktop, OpenAI GPT, Google Gemini).

---

Desteklenen Araçlar

Tarama

Araç	Açıklama
fast_check	Bir URL'nin taranıp taranmadığını anında kontrol edin. SAFE / MALICIOUS / UNRATED döndürür.
new_scan	Bir URL'yi tam tarama için gönderin ve sonucu bekleyin (~30–60 sn).
get_scan	Kimliğe göre tam tarama sonucunu alın.

Arama

Araç	Açıklama
search	CQL (Özel Sorgu Dili) kullanarak alan adı, IP, teknoloji, kötü amaçlı bayrak ve daha fazlası üzerinde taramaları arayın. AND ve OR ifadelerini ve sayfalama destekler (sayfa 2+ PREMIUM gerektirir).

Kayıtlı Sorgular

Araç	Açıklama
list_queries	Kimliği doğrulanmış kullanıcının tüm kayıtlı sorgularını listeler.
get_query	Kimliğe göre belirli bir kayıtlı sorguyu ve filtrelerini alır.
create_query	Bir veya daha fazla CQL filtre koşuluyla yeni bir kayıtlı sorgu oluşturur.
update_query	Mevcut bir sorgunun adını ve filtrelerini günceller (tam değiştirme).
delete_query	Kayıtlı bir sorguyu kimliğe göre kalıcı olarak siler.
query_scans	Kayıtlı bir sorgu için eşleşen tüm taramaları alır.

Marka İzleme

Araç	Açıklama
list_brands	İsteğe bağlı ad araması ve görünürlük filtresiyle (ALL / FREE / PREMIUM / USER_BRANDS) mevcut markaları listeler.
get_brand	Kimliğe göre belirli bir markanın tüm ayrıntılarını alır.
brand_scans	Bir markayla ilişkili tüm taramaları alır. Ek CQL filtrelemeyi destekler.

API Referansı

Araç	Açıklama
search_docs	urlDNA OpenAPI ve dokümantasyonlarının tamamını getirir.

---

Claude Desktop ile Entegrasyon

urlDNA MCP server'i Claude Desktop'a entegre etmek için claude_desktop_config.json dosyanızı güncelleyin:

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

<YOUR_PATH> değerini bu depoyu içeren üst dizinle ve <urlDNA_API_KEY> değerini https://urldna.io adresinden aldığınız API anahtarınızla değiştirin.

Barındırılan MCP istemcileri için onları https://mcp.urldna.io/ veya kendi dağıttığınız MCP_PATH adresine yönlendirin.

Yapılandırıldıktan sonra Claude'a doğal dilde komut verebilirsiniz, örneğin:

"urlDNA'da başlığı paypal gibi olan kötü amaçlı taramaları ara"

"İtalya'dan gelen ve kötü amaçlı olarak işaretlenen mobil taramalar için kayıtlı bir sorgu oluştur"

"Google markasıyla ilişkili tüm taramaları göster"

Claude otomatik olarak doğru aracı çağırır ve urlDNA platformundan sonuçları döndürür.

---

MCP Sunucusunu OpenAI GPT ile Kullanma

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)

---

MCP Sunucusunu Google Gemini ile Kullanma

Gemini, urlDNA MCP sunucusuna fastmcp üzerinden bağlanır ve araçlar bir allowed_tools listesi olarak iletilmek yerine otomatik olarak keşfedilir.

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

---

Konteyner Dağıtımı

Docker ile derleyin ve çalıştırın:

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

Arama Sözdizimi

search ve brand_scans araçları, sağlanan CQL'yi doğrudan urlDNA API'sine iletir. Koşulları AND veya OR ile birleştirebilirsiniz.

Örnekler:

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

---

Katkıda Bulunma

1. Depoyu çatallayın (fork)
2. Bir özellik dalı oluşturun: git checkout -b feature-name
3. Geliştirme bağımlılıklarını kurun: uv sync --dev
4. Değişikliklerinizi yapın ve testlerin geçtiğinden emin olun
5. Kodu biçimlendirin: uv run black .
6. Bir çekme isteği (pull request) gönderin

---

İletişim ve Destek

Destek veya API erişimi için https://urldna.io adresini ziyaret edin veya urldna@urldna.io adresine e-posta gönderin.