Cisco IQ MCP Server

Un servidor local Model Context Protocol (MCP) que expone las API REST de Assets y Assessments de Cisco IQ como herramientas MCP, de modo que un asistente de IA (p. ej. Cursor, Claude Desktop) pueda consultar directamente su inventario de activos con licencia, contratos, datos de ciclo de vida de fin de vida útil, avisos de seguridad y avisos de campo.

[!WARNING] Las API de Cisco IQ están en beta (vista previa pública). Las rutas de los endpoints, los esquemas de solicitud/respuesta, la autenticación, la paginación y el manejo de errores pueden cambiar entre versiones sin mantener compatibilidad con versiones anteriores. No utilice este servidor para integraciones de producción.

Qué hace este servidor

Envuelve las 16 operaciones documentadas de Cisco IQ (a partir de la versión beta 2026-07-24, versión de API 0.1.0) como herramientas MCP de solo lectura:

Todas las herramientas son solo GET; este servidor nunca realiza operaciones de escritura contra Cisco IQ.

El servidor también maneja de forma transparente el flujo de autenticación de dos pasos de Cisco IQ: intercambia su Token de Acceso Personal (PAT) o Token de Cuenta de Servicio (SAT) de larga duración por un token de acceso Bearer de corta duración, lo almacena en caché en memoria y lo renueva automáticamente antes de que expire — de modo que las llamadas a las herramientas nunca requieren que usted piense en tokens.

Related MCP server: Cisco Catalyst SD-WAN MCP Server

Requisitos previos

• Node.js 18 o posterior

• Una cuenta de Cisco IQ con permiso para ver los datos que desea recuperar

• Un Token de Acceso Personal (PAT) o Token de Cuenta de Servicio (SAT) (ver más abajo)

• Su ID de cuenta de Cisco IQ y su Región de almacenamiento de datos (US, EMEA o APJC) — ambos se encuentran en Cisco IQ → Inicio → Configuración del sistema → Detalles de la cuenta

Generación de un token

Token de Acceso Personal (recomendado para uso individual)

1. Inicie sesión en Cisco IQ.

2. Haga clic en su nombre (arriba a la derecha) → Configuración de usuario.

3. En Gestión de tokens personales, haga clic en Generar token.

4. Asígnele un nombre (p. ej. mcp-server), opcionalmente una descripción, y luego haga clic en Generar token.

5. Copie el token inmediatamente — Cisco IQ no lo mostrará de nuevo.

Token de Cuenta de Servicio (para uso compartido/automatización, solo administradores)

1. Inicie sesión en Cisco IQ como administrador.

2. Inicio → Configuración del sistema → Identidad y acceso → Agregar usuario.

3. Seleccione Cuenta de servicio, asígnele un nombre, elija un rol (Administrador o Visor + grupos de recursos) y guarde.

4. Copie el token generado inmediatamente — no se mostrará de nuevo.

Consulte las Prácticas recomendadas de seguridad de tokens de Cisco a continuación antes de almacenarlo.

Configuración

npm install
npm run build

Copie .env.example a .env y complete sus valores (este archivo está en gitignore y nunca debe ser confirmado):

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

Ejecútelo directamente para confirmar que se inicia:

npm start

Debería ver una línea en stderr como:

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

Uso desde Cursor

Agregue una entrada a su mcp.json (Configuración de Cursor → MCP, o ~/.cursor/mcp.json / .cursor/mcp.json en un proyecto). No codifique el valor del token en este archivo si se va a confirmar en una ubicación compartida/sincronizada — prefiera una configuración local con gitignore, o haga referencia a una variable de entorno ya establecida en su perfil de shell.

{
  "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"
      }
    }
  }
}

Para desarrollo local sin compilar, puede ejecutar npm run dev (tsx src/index.ts) como command/args.

Compartir esto con colegas

Este repositorio no contiene credenciales — cada persona que lo use genera y proporciona su propio PAT/SAT (ver Generación de un token arriba). Nunca comparta su propio token con un colega; entréguele este repositorio en su lugar:

1. Clónelo: git clone https://github.com/rrizbaf/cisco-iq-mcp-server.git

2. Siga Configuración para compilarlo y crear su propio .env (o entrada mcp.json) con su propio PAT/SAT, ID de cuenta y región.

3. Las llamadas a herramientas de cada persona se ejecutan bajo su propia identidad y permisos de Cisco IQ — el acceso a activos/contratos específicos está gobernado por Cisco IQ mismo, no por este servidor.

Ejemplos de llamadas a herramientas

Listar hasta 5 activos con avisos de seguridad críticos/altos:

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

Obtener hitos del ciclo de vida de un activo específico:

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

Listar avisos de seguridad que afectan a un activo dado:

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

Paginación, filtrado y selección de campos

• max (1-200, predeterminado 50) y offset controlan el tamaño/posición de la página en cada herramienta de colección.

• Los resultados de las herramientas de colección incluyen un objeto pagination ({ next?, prev? }) tomado del encabezado de respuesta Link de Cisco IQ — pase el offset/max de la URL next de nuevo para la siguiente página. Cisco IQ no devuelve un recuento total de resultados.

• La mayoría de las herramientas de lista aceptan un parámetro fields (separado por comas) para solicitar solo las propiedades que necesita, lo que mantiene las respuestas pequeñas y amigables para el contexto del LLM.

• Los filtros de matriz (p. ej. productFamily, serialNumber) aceptan múltiples valores.

Límites de velocidad y manejo de errores

Cisco IQ aplica límites de velocidad tanto por usuario como por cuenta:

Este servidor reintenta automáticamente 502 Bad Gateway con retroceso exponencial acotado, y 429 Too Many Requests esperando la ventana de restablecimiento documentada más corta (con un tope de 30 segundos para que una sola llamada a herramienta nunca se bloquee indefinidamente). No reintenta 400, 401 (más allá de un intento de renovación de token), 403, 404 o 406 — esos se devuelven al llamante como un error estructurado (status, message, trackingId cuando esté presente) en lugar de reintentarse a ciegas.

Notas de seguridad

• Las credenciales viven solo en variables de entorno, se leen una vez al inicio y se mantienen en memoria. Nunca se registran, se escriben en disco ni se incluyen en mensajes de error.

• .env está en gitignore; solo se confirma .env.example (con marcadores de posición vacíos).

• Los tokens de acceso de corta duración se almacenan en caché solo en memoria y se renuevan automáticamente antes de que expiren; nunca se persisten.

• Según la propia guía de Cisco:

  • Almacene los tokens en un gestor de secretos u otro almacén de credenciales seguro.

  • No ponga tokens en URLs, capturas de pantalla, archivos de registro, código fuente o documentos compartidos.

  • Rote los tokens antes de que expiren; revoque los tokens inmediatamente si se exponen.

  • Use el rol y el acceso a grupos de recursos con menos privilegios requeridos para la integración (prefiera un SAT con rol de Visor limitado a grupos de recursos específicos para automatización de solo lectura).

Estructura del proyecto

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)

Licencia

MIT