cisco-umbrella-mcp

Cisco Umbrella MCP Service — ein zustandsloser HTTP-MCP-Server, der die Cisco Umbrella REST API v2 (klassisches Umbrella, nicht das neuere Secure Access/SASE-Produkt) kapselt, begrenzt auf die 10 Endpunkte, die MSPbots derzeit verwendet: DNS-/Proxy-/Firewall-/AMP-Retrospektiv-Aktivitätsberichte, Roaming-Computer, App-Discovery (Anwendungen/Protokolle/Anwendungskategorien), Kundenliste des Managed Providers und die Provider-Konsolenübersicht.

Tech-Stack: Python 3.12 + uv + FastMCP (Starlette/Uvicorn)

Wann sollte ein Agent dies verwenden

Cisco Umbrella schützt das Netzwerk eines Kunden auf DNS-/Web-Ebene — es blockiert bösartige Domains, filtert Webinhalte nach Kategorie und protokolliert Netzwerkaktivitäten. Ein Agent sollte dieses MCP für Anfragen wie diese verwenden:

• "Wurde diese Domain kürzlich im Netzwerk dieses Kunden abgefragt oder blockiert?" → cisco_umbrella_get_activity_dns

• "Welche Webkategorien/URLs werden für diesen Kunden gefiltert oder über den Proxy geleitet?" → cisco_umbrella_get_activity_proxy

• "Gab es in den letzten 24 Stunden Firewall-Zulassungen/-Blockierungen für das Netzwerk dieses Kunden?" → cisco_umbrella_get_activity_firewall

• "Wurde eine Datei, die sauber aussah, später als Malware eingestuft?" → cisco_umbrella_get_activity_amp_retrospective

• "Liste die Roaming-Laptops dieses Kunden und ihren letzten Synchronisierungsstatus auf" → cisco_umbrella_list_roaming_computers

• "Liste die Kundenorganisationen auf, die wir unter Cisco Umbrella verwalten" / "Wie ist unsere Umbrella-Paketnutzung über alle Kunden hinweg?" → cisco_umbrella_list_customers, cisco_umbrella_get_providers_console

Hinweis: Dieser Anmeldedatensatz ist ein Managed-Provider-Key (MSSP) der Root-Organisation, kein kundenspezifischer Anmeldedatensatz. Die kundenbezogenen Aktivitäts-/Geräte-Tools oben können daher in der Praxis leer zurückkommen — siehe Bekannte Lücken unten für die verifizierten Details.

Related MCP server: cisco-secure-access-mcp

Hinweis zur Authentifizierungsmethode

Die klassische REST-API von Cisco Umbrella unterstützt den OAuth2 client_credentials-Grant — ein reiner Server-zu-Server-Austausch ohne Browser-Weiterleitung des Benutzers. Ein Administrator erstellt ein Paar aus API-Key und Key-Secret im Umbrella-Dashboard (Admin > API Keys), und dieser Dienst tauscht dieses Paar bei jedem Aufruf gegen ein kurzlebiges (1 Stunde) Bearer-Token ein (kein Refresh-Token, also kein Caching über Anfragen hinweg — dasselbe „Bei jedem Aufruf neu anmelden"-Muster wie covedataprotection-mcp/webroot-mcp/logmein-mcp).

POST https://api.umbrella.com/auth/v2/token
Authorization: Basic base64(apiKey:keySecret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Hinweis zur Region: Die eigene Integrationskonfiguration von MSPbots für Cisco Umbrella enthält ein Feld dataCenter (us/eu). Direkt gegen die rohe OpenAPI-Spezifikation verifiziert, die in Ciscos eigenen Entwicklerdokumenten für alle 10 Endpunkte plus den Auth-/Token-Endpunkt eingebettet ist: Jeder von ihnen listet genau einen Host, https://api.umbrella.com — es gibt keinen separaten EU-Host für klassisches Umbrella. (Ciscos neueres Produkt „Secure Access" hat zwar ein eigenes Regionskonzept, aber das ist ein anderes Produkt als das, auf das dieser Dienst abzielt.) Dieser Dienst ignoriert daher den Wert von dataCenter vollständig; er wird für keinen dieser 10 Endpunkte benötigt.

Schnellstart

# Install dependencies
cd D:\claude\project\cisco-umbrella-mcp
uv sync

# Run in stdio mode (for Claude Desktop)
$env:UMBRELLA_API_KEY="your_api_key"
$env:UMBRELLA_KEY_SECRET="your_key_secret"
uv run cisco-umbrella-mcp

Konfiguration

Kopieren Sie .env.example in .env und füllen Sie Ihre Werte aus:

HEADER-Autorisierungsparameter

Im Gateway-Modus muss jede Anfrage die folgenden zwei HTTP-Header enthalten:

Claude Desktop Einrichtung

Fügen Sie Folgendes zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "cisco-umbrella": {
      "command": "uv",
      "args": ["run", "--directory", "D:/claude/project/cisco-umbrella-mcp", "cisco-umbrella-mcp"],
      "env": {
        "UMBRELLA_API_KEY": "your_api_key",
        "UMBRELLA_KEY_SECRET": "your_key_secret"
      }
    }
  }
}

Transportmodi

stdio (Claude Desktop / CLI)

$env:UMBRELLA_API_KEY="your_api_key"
$env:UMBRELLA_KEY_SECRET="your_key_secret"
uv run cisco-umbrella-mcp

HTTP — Einzelmandant

$env:UMBRELLA_API_KEY="your_api_key"
$env:UMBRELLA_KEY_SECRET="your_key_secret"
$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="env"
uv run cisco-umbrella-mcp

HTTP — Gateway / Mehrfachmandant

$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="gateway"
uv run cisco-umbrella-mcp
# Each request must include: X-Umbrella-Api-Key and X-Umbrella-Key-Secret headers

Verfügbare Tools (10)

from_/to akzeptieren Epochen-Millisekunden, ISO-8601 oder einen relativen Offset (z. B. "-1days", "-7days", "now"), gemäß den Konventionen der Umbrella-Reporting-API. (from_ hat einen nachgestellten Unterstrich, weil from ein reserviertes Wort in Python ist — es wird intern auf den Literal-Query-Parameter from abgebildet.)

Bekannte Lücken

Getestet gegen zwei echte Managed-Provider-Konten (MSSP). Von den 10 Tools sind nur 2 mit verifizierten echten Daten bestätigt funktionsfähig; die anderen 8 sind entweder blockiert oder unverifiziert (leere Ergebnisse beweisen keine Korrektheit — sie bedeuten nur, dass kein Fehler ausgelöst wurde).

✅ Bestätigt funktionsfähig (echte, nicht leere, kreuzvalidierte Daten):

• cisco_umbrella_get_providers_console — echte Abonnementübersicht auf beiden Testkonten (customerCount: 77 bzw. customerCount: 47).

• cisco_umbrella_list_customers — lieferte 77 echte Kundenorganisationen (echte Firmennamen) auf Konto 1. Fehlgeschlagen mit 403 Access Forbidden auf Konto 2 — durch Dekodierung des Tokens dieses Kontos bestätigt, dass ihm tatsächlich der Bereich admin.customers:read fehlt (20 Bereiche insgesamt gegenüber 76 auf Konto 1). Kein Codefehler; ein echter Unterschied in den Berechtigungen pro Schlüssel.

⚠️ Unverifiziert — lieferte wohlgeformte, aber leere Ergebnisse auf beiden Konten, nicht als korrekt nachgewiesen: cisco_umbrella_get_activity_dns, _proxy, _firewall, _amp_retrospective, cisco_umbrella_list_roaming_computers. Die Live-OpenAPI-Parameterdefinitionen für Activity DNS wurden direkt gegen Ciscos eigene Dokumentation kreuzgeprüft (die rohe Spezifikation abgerufen, nicht zusammengefasst) — from/to/limit sind exakt wie implementiert, keine fehlenden oder falsch benannten Parameter. Die wahrscheinliche Erklärung ist, dass beide Testkonten Managed-Provider-Root-Organisationen sind, die selbst keinen direkten DNS-/Proxy-/Firewall-/AMP-Verkehr oder Roaming-Computer haben — diese Daten liegen jeweils unter jeder einzelnen verwalteten Kundenorganisation. In Ciscos Dokumentation wurde nach einem Parameter/Header zur Bereichsbegrenzung „Abfrage als diese Kundenorganisation" für klassisches Umbrella gesucht — keiner gefunden (ein „Multi-Org"-Token-Bereichskonzept existiert, aber nur für das separate Secure Access/SASE-Produkt, nicht für klassisches Umbrella). Es gibt eine eigene „Providers"-API-Familie (/providers/customers/{customerId}/...), die wie der vorgesehene Weg zu kundenspezifischen Daten aussieht, aber sie liegt außerhalb des für diesen Build bestätigten 10-Endpunkt-Umfangs. Es wird ein echter Anmeldedatensatz einer einzelnen Kundenorganisation (nicht auf Provider-Ebene) benötigt, um diese 5 tatsächlich zu bestätigen.

• cisco_umbrella_list_applications, _protocols, _application_categories (App Discovery) — bestätigt blockiert, kein Code-Fehler. Auf beiden Testkonten und per direktem curl mit denselben Tokens identisch reproduziert (was Probleme bei der Anfragekonstruktion ausschließt): 403 Access Forbidden auf Konto 1, 500/403 auf Konto 2. Die Scope-Listen beider Tokens enthielten reports.appdiscovery:read, daher handelt es sich höchstwahrscheinlich um eine Paket-/Berechtigungseinschränkung (App Discovery als kostenpflichtiges Add-on, das in keinem der „Umbrella for MSSPs“-Tarife der Konten enthalten ist), nicht um ein Berechtigungs- oder Parameterproblem.

• cisco_umbrella_get_providers_console gibt ein einzelnes Abonnement-Zusammenfassungsobjekt zurück, keine Liste — durch beide Live-Tests bestätigt. Trotz des Pluralnamens in MSPbots‘ eigener konfigurierter API-Liste („Providers Consoles“) sollte dies gegen das geprüft werden, was MSPbots‘ bestehender Collector erwartet (Array vs. einzelnes Objekt).

• Die optionale Parameterliste des Applications-App-Discovery-Endpunkts ist möglicherweise nicht vollständig erschöpfend (einige Parameter am Ende des Schemas dieses Endpunkts wurden während der Recherche nicht vollständig erfasst) — die hier dokumentierten (sources, identity, labels, controllable, categories, subcategory, limit, offset) sind als real bestätigt; es könnten noch ein oder zwei weitere fehlen.

• Der Umfang ist auf die 10 Operationen beschränkt, die MSPbots derzeit verwendet (vom Benutzer bestätigt), nicht auf die vollständige API-Oberfläche von Umbrella (die auch Networks, Internal Domains, Sites, Network Tunnels, Policies, Tagging, die separate „Providers“-API für kundenbezogene Aktionen und die Key Admin API zur Verwaltung der API-Schlüssel selbst umfasst).

API-Referenz

• Cisco Umbrella API-Authentifizierung

• Cisco Cloud Security API-Dokumentation (DevNet)