Cisco IQ MCP Server

Ein lokaler Model Context Protocol (MCP)-Server, der die Assets- und Assessments-REST-APIs von Cisco IQ als MCP-Tools bereitstellt, sodass ein KI-Assistent (z. B. Cursor, Claude Desktop) direkt Ihr berechtigtes Asset-Inventar, Verträge, End-of-Life-Lebenszyklusdaten, Sicherheitshinweise und Field Notices abfragen kann.

[!WARNING] Die Cisco IQ APIs befinden sich in der Beta-Phase (öffentliche Vorschau). Endpunktpfade, Anfrage-/Antwortschemata, Authentifizierung, Paginierung und Fehlerbehandlung können sich zwischen Releases ändern, ohne die Abwärtskompatibilität zu wahren. Verwenden Sie diesen Server nicht für Produktionsintegrationen.

Was dieser Server tut

Er kapselt die 16 dokumentierten Cisco IQ-Operationen (Stand des Beta-Releases vom 2026-07-24, API-Version 0.1.0) als schreibgeschützte MCP-Tools:

Alle Tools sind reine GET-Operationen; dieser Server führt niemals Schreiboperationen gegen Cisco IQ aus.

Der Server übernimmt außerdem transparent den zweistufigen Authentifizierungsablauf von Cisco IQ: Er tauscht Ihr langlebiges Personal Access Token (PAT) oder Service Account Token (SAT) gegen ein kurzlebiges Bearer-Zugriffstoken, speichert es im Speicher zwischen und aktualisiert es automatisch vor Ablauf – so müssen Sie bei Tool-Aufrufen nie über Tokens nachdenken.

Related MCP server: Cisco Catalyst SD-WAN MCP Server

Voraussetzungen

• Node.js 18 oder höher

• Ein Cisco IQ-Konto mit der Berechtigung, die Daten anzuzeigen, die Sie abrufen möchten

• Ein Personal Access Token (PAT) oder Service Account Token (SAT) (siehe unten)

• Ihre Cisco IQ-Account-ID und Data Storage Region (US, EMEA oder APJC) – beides finden Sie unter Cisco IQ → Home → System Settings → Account Details

Generieren eines Tokens

Personal Access Token (empfohlen für die individuelle Nutzung)

1. Melden Sie sich bei Cisco IQ an.

2. Klicken Sie auf Ihren Namen (oben rechts) → User Settings.

3. Klicken Sie unter Personal Token Management auf Generate Token.

4. Geben Sie ihm einen Namen (z. B. mcp-server), optional eine Beschreibung, und klicken Sie dann auf Generate Token.

5. Kopieren Sie das Token sofort – Cisco IQ zeigt es nicht erneut an.

Service Account Token (für gemeinsame/Automatisierungsnutzung, nur Administratoren)

1. Melden Sie sich als Administrator bei Cisco IQ an.

2. Home → System Settings → Identity and Access → Add User.

3. Wählen Sie Service Account, benennen Sie es, wählen Sie eine Rolle (Administrator oder Viewer + Ressourcengruppen) und speichern Sie.

4. Kopieren Sie das generierte Token sofort – es wird nicht erneut angezeigt.

Lesen Sie vor der Speicherung die Token-Sicherheitsempfehlungen von Cisco unten.

Setup

npm install
npm run build

Kopieren Sie .env.example in .env und füllen Sie Ihre Werte aus (diese Datei ist gitignored und darf niemals committet werden):

cp .env.example .env

# Exactly one of these:
CISCO_IQ_PAT=your-personal-access-token
# CISCO_IQ_SAT=your-service-account-token

# Required for PAT auth; optional (but must match) for SAT auth
CISCO_IQ_ACCOUNT_ID=your-account-id

# Required: US, EMEA, or APJC
CISCO_IQ_REGION=APJC

Führen Sie es direkt aus, um zu bestätigen, dass es startet:

npm start

Sie sollten eine Zeile auf stderr sehen wie:

[cisco-iq-mcp-server] Ready (region=APJC, auth=PAT). Cisco IQ APIs are beta/public preview - do not use for production integrations.

Verwendung in Cursor

Fügen Sie einen Eintrag zu Ihrer mcp.json hinzu (Cursor Settings → MCP, oder ~/.cursor/mcp.json / .cursor/mcp.json in einem Projekt). Harten Sie den Token-Wert nicht in dieser Datei ein, wenn sie an einem gemeinsamen/synchronisierten Ort committet wird – bevorzugen Sie eine lokale, gitignored Konfiguration oder referenzieren Sie eine Umgebungsvariable, die bereits in Ihrem Shell-Profil gesetzt ist.

{
  "mcpServers": {
    "cisco-iq": {
      "command": "node",
      "args": ["/absolute/path/to/cisco-iq-mcp-server/dist/index.js"],
      "env": {
        "CISCO_IQ_PAT": "your-personal-access-token",
        "CISCO_IQ_ACCOUNT_ID": "your-account-id",
        "CISCO_IQ_REGION": "APJC"
      }
    }
  }
}

Für die lokale Entwicklung ohne Build können Sie stattdessen npm run dev (tsx src/index.ts) als command/args ausführen.

Teilen mit Kollegen

Dieses Repo enthält keine Anmeldeinformationen – jeder, der es verwendet, generiert und liefert sein eigenes PAT/SAT (siehe Generating a token oben). Teilen Sie Ihr eigenes Token niemals mit einem Kollegen; geben Sie ihnen stattdessen dieses Repo:

1. Klonen Sie es: git clone https://github.com/rrizbaf/cisco-iq-mcp-server.git

2. Folgen Sie Setup, um es zu bauen und ihre eigene .env (oder mcp.json-Eintrag) mit ihrem eigenen PAT/SAT, Account-ID und Region zu erstellen.

3. Die Tool-Aufrufe jeder Person laufen unter ihrer eigenen Cisco IQ-Identität und ihren Berechtigungen – der Zugriff auf bestimmte Assets/Verträge wird von Cisco IQ selbst geregelt, nicht von diesem Server.

Beispiel-Tool-Aufrufe

Listen Sie bis zu 5 Assets mit kritischen/hohen Sicherheitshinweisen auf:

{ "name": "list_assets", "arguments": { "hasCriticalOrHighSecurityAdvisories": true, "max": 5 } }

Rufen Sie Lebenszyklus-Meilensteine für ein bestimmtes Asset ab:

{ "name": "get_asset_lifecycle", "arguments": { "assetId": "85f9981e37312238b5c73020031a7b36", "milestoneType": "software" } }

Listen Sie Sicherheitshinweise auf, die ein bestimmtes Asset betreffen:

{ "name": "list_asset_security_advisories", "arguments": { "assetId": "85f9981e37312238b5c73020031a7b36", "impact": ["Critical", "High"] } }

Paginierung, Filterung und Feldauswahl

• max (1-200, Standard 50) und offset steuern Seitengröße/-position bei jedem Sammlungstool.

• Die Ergebnisse der Sammlungstools enthalten ein pagination-Objekt ({ next?, prev? }), das aus dem Link-Antwortheader von Cisco IQ stammt – geben Sie das offset/max der next-URL für die nächste Seite zurück. Cisco IQ gibt keine Gesamtzahl der Ergebnisse zurück.

• Die meisten Listentools akzeptieren einen fields-Parameter (kommagetrennt), um nur die benötigten Eigenschaften anzufordern, was die Antworten klein und LLM-kontextfreundlich hält.

• Array-Filter (z. B. productFamily, serialNumber) akzeptieren mehrere Werte.

Ratenlimits und Fehlerbehandlung

Cisco IQ erzwingt sowohl Pro-Benutzer- als auch Pro-Konto-Ratenlimits:

Dieser Server wiederholt automatisch 502 Bad Gateway mit begrenztem exponentiellem Backoff und 429 Too Many Requests, indem er auf das kürzeste dokumentierte Reset-Fenster wartet (auf 30 Sekunden begrenzt, sodass ein einzelner Tool-Aufruf nie unbegrenzt blockiert). Er wiederholt nicht 400, 401 (über einen Token-Refresh-Versuch hinaus), 403, 404 oder 406 – diese werden dem Aufrufer als strukturierter Fehler (status, message, trackingId falls vorhanden) zurückgegeben, anstatt blind wiederholt zu werden.

Sicherheitshinweise

• Anmeldeinformationen leben nur in Umgebungsvariablen, werden einmal beim Start gelesen und im Speicher gehalten. Sie werden niemals protokolliert, auf die Festplatte geschrieben oder in Fehlermeldungen aufgenommen.

• .env ist gitignored; nur .env.example (mit leeren Platzhaltern) wird committet.

• Kurzlebige Zugriffstokens werden nur im Speicher zwischengespeichert und automatisch vor Ablauf aktualisiert; sie werden niemals persistiert.

• Gemäß den eigenen Richtlinien von Cisco:

  • Speichern Sie Tokens in einem Secrets Manager oder einem anderen sicheren Anmeldeinformationsspeicher.

  • Platzieren Sie Tokens nicht in URLs, Screenshots, Logdateien, Quellcode oder gemeinsamen Dokumenten.

  • Rotieren Sie Tokens vor Ablauf; widerrufen Sie Tokens sofort, wenn sie offengelegt wurden.

  • Verwenden Sie die Rolle mit den geringsten Rechten und den Ressourcengruppenzugriff, der für die Integration erforderlich ist (bevorzugen Sie ein SAT mit Viewer-Rolle, das auf bestimmte Ressourcengruppen für schreibgeschützte Automatisierung beschränkt ist).

Projektstruktur

src/
  config.ts             # env-var loading & validation (no hardcoded secrets)
  auth.ts               # TokenManager: PAT/SAT -> short-lived Bearer token
  client.ts             # CiqClient: query building, pagination, retry/backoff
  errors.ts             # CiqApiError + error-body parsing
  types.ts              # TS interfaces for documented response schemas
  tools/
    shared.ts           # common Zod schemas & MCP result helpers
    assets.ts            # 6 asset-related tools
    contracts.ts         # 2 contract-related tools
    securityAdvisories.ts # 4 security-advisory tools
    fieldNotices.ts       # 4 field-notice tools
  index.ts              # MCP server entrypoint (stdio transport)

Lizenz

MIT