Cisco IQ MCP Server

ローカルで動作する Model Context Protocol (MCP) サーバーで、Cisco IQ の Assets および Assessments REST API を MCP ツールとして公開します。これにより、AI アシスタント（例: Cursor、Claude Desktop）が、権限のあるアセットインベントリ、契約、EOL（製品終了）ライフサイクルデータ、セキュリティ勧告、フィールド通知を直接照会できます。

[!WARNING] Cisco IQ API はベータ版（パブリックプレビュー）です。 エンドポイントパス、リクエスト/レスポンススキーマ、認証、ページネーション、エラーハンドリングは、後方互換性を維持せずにリリース間で変更される可能性があります。本番統合にはこのサーバーを使用しないでください。

このサーバーの機能

Cisco IQ のドキュメント化された16の操作（2026-07-24 ベータリリース、API バージョン 0.1.0 時点）を読み取り専用の MCP ツールとしてラップします：

すべてのツールは GET のみです。このサーバーが Cisco IQ に対して書き込み操作を行うことはありません。

また、このサーバーは Cisco IQ の2段階認証フローを透過的に処理します。長期有効な Personal Access Token（PAT）または Service Account Token（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. ホーム → システム設定 → ID とアクセス → ユーザーの追加 を選択します。

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 された設定を優先するか、シェルプロファイルで既に設定されている環境変数を参照してください。

{
  "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. セットアップ に従ってビルドし、自分の PAT/SAT、アカウント ID、リージョンを指定して独自の .env（または mcp.json エントリ）を作成します。

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 は、すべてのコレクションツールでページサイズ/位置を制御します。

• コレクションツールの結果には、Cisco IQ の Link レスポンスヘッダーから取得した pagination オブジェクト（{ next?, prev? }）が含まれます。次のページには、next URL の offset/max を渡します。Cisco IQ は結果の総数を返しません。

• ほとんどのリストツールは fields パラメータ（カンマ区切り）を受け入れ、必要なプロパティのみをリクエストできるため、レスポンスを小さく保ち、LLM のコンテキストに優しくします。

• 配列フィルター（例: productFamily、serialNumber）は複数の値を受け入れます。

レート制限とエラーハンドリング

Cisco IQ は、ユーザーごととアカウントごとの両方のレート制限を適用します：

このサーバーは、502 Bad Gateway を上限付きの指数バックオフで自動的に再試行し、429 Too Many Requests は、ドキュメント化された最短のリセットウィンドウを待って再試行します（単一のツール呼び出しが無期限にブロックされないよう30秒で上限）。400、401（トークン更新の1回の試行を除く）、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