Cisco IQ MCP 服务器

一个本地 Model Context Protocol（MCP）服务器，将 Cisco IQ 的 Assets 和 Assessments REST API 暴露为 MCP 工具，使 AI 助手（例如 Cursor、Claude Desktop）能够直接查询您的授权资产清单、 合同、生命周期终止数据、安全公告和现场通告。

[!WARNING] Cisco IQ API 处于测试阶段（公开预览）。 端点路径、请求/响应 模式、身份验证、分页和错误处理可能会在版本之间发生变化，且不保持向后兼容。 请勿将此服务器用于生产环境集成。

此服务器的功能

它将 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）（见下文）

• 您的 Cisco IQ 账户 ID 和 数据存储区域（US、EMEA 或 APJC）——两者均可在 Cisco IQ → 首页 → 系统设置 → 账户详情 中找到

生成令牌

个人访问令牌（推荐个人使用）

1. 登录 Cisco IQ。

2. 点击您的姓名（右上角）→ 用户设置。

3. 在 个人令牌管理 下，点击 生成令牌。

4. 为其命名（例如 mcp-server），可选添加描述，然后点击 生成令牌。

5. 立即复制令牌 —— Cisco IQ 不会再次显示它。

服务账户令牌（用于共享/自动化使用，仅限管理员）

1. 以管理员身份登录 Cisco IQ。

2. 首页 → 系统设置 → 身份与访问 → 添加用户。

3. 选择 服务账户，为其命名，选择角色（管理员 或 查看者 + 资源组），然后保存。

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 设置 → MCP，或项目中的 ~/.cursor/mcp.json / .cursor/mcp.json）。如果此文件将被提交到共享/同步位置，请勿在其中硬编码令牌值 ——建议使用本地、已 gitignore 的配置，或引用已在您的 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"
      }
    }
  }
}

对于无需构建的本地开发，您可以改为将 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、账户 ID 和区域。

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? }），取自 Cisco IQ 的 Link 响应头——将 next URL 的 offset/max 传回以获取 下一页。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、截图、日志文件、源代码或共享文档中。

  • 在令牌过期前轮换令牌；如果令牌泄露，立即撤销。

  • 使用集成所需的最低权限角色和资源组访问权限 （对于只读自动化，优先使用限定于特定资源组的查看者角色 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