yads-mcp

MCP-Server, der es jedem MCP-fähigen LLM-Agenten (Claude Code oder einem anderen Agentenprozess, der über dasselbe Netzwerk wie YADS erreichbar ist) ermöglicht, die Warteschlangensteuerung, das Tagging, die Scan-Ausführung und die Ziel-/Asset-Verwaltung über YADS' eigene /api/v1-API zu steuern – ohne einen Menschen am Dashboard.

Es ist ein schlanker stdio-Wrapper um YADS' bestehende HTTP-API (/api/v1/queue/*, /api/v1/tags*, /api/v1/targets/*) – kein separater Ausführungspfad, kein Umgehen der Tenant-Abgrenzung oder des Scan-Dispatch-Codepfads. Jede Aktion, die hierüber ausgeführt wird, unterliegt derselben Tenant-Isolation, denselben Grenzen für gleichzeitige Scans und derselben Änderungserkennungslogik wie das Dashboard.

1. API-Schlüssel erstellen

Von einem Rechner, der bereits bei YADS angemeldet ist (Session-Cookie), über /developer oder den /api-keys/-Endpunkt einen Schlüssel mit den Bereichen erstellen, die dieser Agent benötigt:

• read – Status-/Listenoperationen (queue_status, tags_list, scan_get_findings, list_targets, get_target, get_target_changes, get_scan_status, get_network_context, ...)

• write – Tag-Änderungen und Ziel-Änderungen (add_target, undo_bulk_delete_targets, bulk_archive_targets, archive_dead_targets, restore_target)

• scan_execute – Auslösen von Scans (einzeln oder in Bulk)

• destructive – queue_purge, tags_delete_globally, bulk_delete_targets, bulk_blocklist_targets (erfordert zusätzlich confirm=True beim Aufruf selbst)

Kopieren Sie das zurückgegebene Token jetzt – es wird nie wieder angezeigt.

Related MCP server: agentguard

2. Installation

cd yads-mcp
python -m venv .venv
.venv/bin/pip install -e .

Tests

.venv/bin/pip install -e ".[test]"
.venv/bin/pytest tests/ -q

tests/conftest.py führt YADS prozessintern aus (Starlette TestClient) gegen denselben Test-Postgres/Redis-Stack wie die Tests des yads-Repos (docker-compose.test.yml in diesem Repo, Ports 5433/6380) – starten Sie diesen Stack zuerst, falls diese Tests nicht durchlaufen.

3. Client konfigurieren

Umgebungsvariablen, die der Server benötigt:

• YADS_URL – z. B. https://yads.example.com

• YADS_API_KEY – das Token aus Schritt 1

Claude Code

claude mcp add yads \
  --env YADS_URL=https://yads.example.com \
  --env YADS_API_KEY=<token> \
  -- /path/to/yads-mcp/.venv/bin/python -m yads_mcp.server

oder zu .mcp.json hinzufügen:

{
  "mcpServers": {
    "yads": {
      "command": "/path/to/yads-mcp/.venv/bin/python",
      "args": ["-m", "yads_mcp.server"],
      "env": {
        "YADS_URL": "https://yads.example.com",
        "YADS_API_KEY": "<token>"
      }
    }
  }
}

Tools

Warteschlangen- und Scan-Steuerung

• queue_status()

• queue_list_rate_limited_modules()

• queue_pause() / queue_resume() – flottenweit, nicht tenant-bezogen

• queue_cancel_task(task_id)

• queue_purge(confirm) – destruktiv, tenant-bezogen, 60s Rückgängig-Fenster

• queue_undo_purge(undo_batch)

Tagging & Organisation

• tags_list()

• tags_add_to_target(target_id, tag) / tags_remove_from_target(target_id, tag)

• tags_bulk_assign(target_ids, tags, action="add"|"remove"|"replace")

• tags_bulk_add_by_ids(target_ids, tag)

• tags_delete_globally(tag_name, confirm) – destruktiv, kein Rückgängig

Scan-Ausführung

• scan_trigger(target_url, profile="standard")

• scan_trigger_by_target_id(target_id, scan_types, scan_priority=None)

• scan_bulk_preview_count(only_roots=False, online_only=False, scanned_before=None)

• scan_bulk_by_criteria(scan_types, only_roots=False, online_only=False, scanned_before=None)

• scan_bulk_selected(target_ids, scan_types)

• scan_get_findings()

Ziel- & Asset-Verwaltung (Wave 2)

• list_targets(tag=None, online=None, scan_status=None, domain_search=None, archived=False, last_scanned_before=None, page=1, limit=20)

• get_target(target_id)

• add_target(domain)

• bulk_delete_targets(target_ids, confirm) – destruktiv, 60s Rückgängig-Fenster

• undo_bulk_delete_targets(undo_batch)

• bulk_archive_targets(target_ids) / archive_dead_targets() / restore_target(target_id)

• bulk_blocklist_targets(target_ids, confirm) – destruktiv, kein Rückgängig

• get_target_changes(target_id, limit=30)

• get_scan_status(target_id)

• get_network_context(target_id)

Waves 3–10 (Berichte & Export, Findings & Compliance, OSINT/Discovery/Intelligence, Integrationen/Webhooks/Benachrichtigungen) werden separat verfolgt, jeweils mit eigener Design-Spezifikation.

Änderungsprotokoll

Siehe CHANGELOG.md.

Lizenz

MIT – siehe LICENSE.