Cisco IQ MCP Server

Локальный Model Context Protocol (MCP) сервер, который предоставляет REST API Assets и Assessments сервиса Cisco IQ в виде MCP-инструментов, чтобы ИИ-ассистент (например, Cursor, Claude Desktop) мог напрямую запрашивать ваш инвентарь активов, контракты, данные жизненного цикла, уведомления безопасности и полевые извещения.

[!WARNING] API Cisco IQ находятся в стадии бета-тестирования (публичная предварительная версия). Пути конечных точек, схемы запросов/ответов, аутентификация, пагинация и обработка ошибок могут меняться между релизами без сохранения обратной совместимости. Не используйте этот сервер для производственных интеграций.

Что делает этот сервер

Он оборачивает 16 документированных операций Cisco IQ (по состоянию на бета-релиз 2026-07-24, версия API 0.1.0) в инструменты MCP, доступные только для чтения:

Все инструменты работают только на GET; этот сервер никогда не выполняет операций записи в Cisco IQ.

Сервер также прозрачно обрабатывает двухэтапный процесс аутентификации Cisco IQ: он обменивает ваш долгоживущий персональный токен доступа (PAT) или токен сервисной учетной записи (SAT) на кратковременный Bearer-токен доступа, кэширует его в памяти и автоматически обновляет до истечения срока действия — так что вам никогда не придется думать о токенах при вызовах инструментов.

Related MCP server: Cisco Catalyst SD-WAN MCP Server

Предварительные требования

• Node.js 18 или новее

• Учетная запись Cisco IQ с разрешением на просмотр данных, которые вы хотите получить

• Персональный токен доступа (PAT) или токен сервисной учетной записи (SAT) (см. ниже)

• Ваш Account ID и Data Storage Region (US, EMEA или APJC) Cisco IQ — оба значения можно найти в Cisco IQ → Home → System Settings → Account Details

Создание токена

Персональный токен доступа (рекомендуется для индивидуального использования)

1. Войдите в Cisco IQ.

2. Нажмите на свое имя (в правом верхнем углу) → User Settings.

3. В разделе Personal Token Management нажмите Generate Token.

4. Дайте ему имя (например, mcp-server), при желании добавьте описание, затем нажмите Generate Token.

5. Скопируйте токен немедленно — Cisco IQ больше не покажет его.

Токен сервисной учетной записи (для общего/автоматизированного использования, только для администраторов)

1. Войдите в Cisco IQ как администратор.

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

3. Выберите Service Account, дайте ему имя, выберите роль (Administrator или Viewer + группы ресурсов) и сохраните.

4. Скопируйте сгенерированный токен немедленно — он больше не будет показан.

Перед сохранением ознакомьтесь с рекомендациями по безопасности токенов от Cisco ниже.

Настройка

npm install
npm run build

Скопируйте .env.example в .env и заполните свои значения (этот файл находится в .gitignore и никогда не должен попадать в репозиторий):

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

Запустите его напрямую, чтобы убедиться, что он запускается:

npm start

Вы должны увидеть строку в stderr, например:

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

Использование из Cursor

Добавьте запись в ваш mcp.json (Cursor Settings → MCP или ~/.cursor/mcp.json / .cursor/mcp.json в проекте). Не прописывайте значение токена в этом файле, если он будет закоммичен в общее/синхронизируемое место — используйте локальный конфиг, добавленный в .gitignore, или ссылайтесь на переменную окружения, уже заданную в вашем профиле оболочки.

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

Для локальной разработки без сборки вы можете вместо этого запустить npm run dev (tsx src/index.ts) в качестве command/args.

Как поделиться с коллегами

Этот репозиторий не содержит учетных данных — каждый, кто его использует, генерирует и предоставляет собственный PAT/SAT (см. Создание токена выше). Никогда не передавайте свой токен коллеге; вместо этого дайте им этот репозиторий:

1. Склонируйте его: git clone https://github.com/rrizbaf/cisco-iq-mcp-server.git

2. Следуйте Настройке, чтобы собрать его и создать собственный .env (или запись в mcp.json) со своими PAT/SAT, Account ID и Region.

3. Вызовы инструментов каждого пользователя выполняются под его собственной учетной записью Cisco IQ и правами — доступ к конкретным активам/контрактам управляется самим Cisco IQ, а не этим сервером.

Примеры вызовов инструментов

Вывести до 5 активов с критическими/высокими уведомлениями безопасности:

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

Получить вехи жизненного цикла для конкретного актива:

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

Вывести уведомления безопасности, влияющие на указанный актив:

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

Пагинация, фильтрация и выбор полей

• max (1-200, по умолчанию 50) и offset управляют размером/позицией страницы в каждом инструменте коллекций.

• Результаты инструментов коллекций включают объект pagination ({ next?, prev? }), взятый из заголовка ответа Link от Cisco IQ — передайте offset/max из URL next обратно для следующей страницы. Cisco IQ не возвращает общее количество результатов.

• Большинство инструментов списков принимают параметр fields (через запятую), чтобы запрашивать только нужные свойства, что делает ответы компактными и удобными для контекста LLM.

• Фильтры массивов (например, productFamily, serialNumber) принимают несколько значений.

Лимиты запросов и обработка ошибок

Cisco IQ применяет лимиты запросов как на пользователя, так и на учетную запись:

Этот сервер автоматически повторяет запросы при 502 Bad Gateway с ограниченной экспоненциальной задержкой, а при 429 Too Many Requests — ожидая кратчайшее документированное окно сброса (не более 30 секунд, чтобы один вызов инструмента никогда не блокировался бесконечно). Он не повторяет 400, 401 (кроме одной попытки обновления токена), 403, 404 или 406 — они возвращаются вызывающему коду как структурированная ошибка (status, message, trackingId при наличии) вместо слепых повторных попыток.

Примечания по безопасности

• Учетные данные хранятся только в переменных окружения, считываются один раз при запуске и хранятся в памяти. Они никогда не записываются в журналы, не сохраняются на диск и не включаются в сообщения об ошибках.

• .env находится в .gitignore; в репозиторий попадает только .env.example (с пустыми заполнителями).

• Кратковременные токены доступа кэшируются только в памяти и автоматически обновляются до истечения срока действия; они никогда не сохраняются на диск.

• Следуя рекомендациям Cisco:

  • Храните токены в менеджере секретов или другом защищенном хранилище учетных данных.

  • Не помещайте токены в URL-адреса, скриншоты, файлы журналов, исходный код или общие документы.

  • Ротируйте токены до истечения срока действия; немедленно отзывайте токены при утечке.

  • Используйте роль с минимальными привилегиями и доступом к группам ресурсов, необходимыми для интеграции (для автоматизации только на чтение предпочтительна роль Viewer для SAT с областью действия на конкретные группы ресурсов).

Структура проекта

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)

Лицензия

MIT