Cisco IQ MCP Server

로컬 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의 2단계 인증 흐름을 투명하게 처리합니다. 장기간 유효한 PAT(Personal Access Token) 또는 SAT(Service Account Token)를 단기 Bearer 액세스 토큰으로 교환하고, 메모리에 캐시한 뒤 만료 전에 자동으로 갱신합니다. 따라서 도구 호출 시 토큰에 대해 신경 쓸 필요가 없습니다.

Related MCP server: Cisco Catalyst SD-WAN MCP Server

사전 요구 사항

• Node.js 18 이상

• 조회하려는 데이터를 볼 수 있는 권한이 있는 Cisco IQ 계정

• PAT(Personal Access Token) 또는 SAT(Service Account Token) (아래 참조)

• Cisco IQ Account ID 및 Data Storage Region (US, EMEA, APJC) — 둘 다 Cisco IQ → Home → System Settings → Account Details에서 확인할 수 있습니다.

토큰 생성

Personal Access Token (개인 사용 권장)

1. Cisco IQ에 로그인합니다.

2. 오른쪽 상단의 이름을 클릭 → User Settings.

3. Personal Token Management에서 Generate Token을 클릭합니다.

4. 이름(예: mcp-server)을 지정하고, 선택적으로 설명을 입력한 다음 Generate Token을 클릭합니다.

5. 토큰을 즉시 복사하세요. — Cisco IQ는 토큰을 다시 표시하지 않습니다.

Service Account Token (공유/자동화용, 관리자 전용)

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

빌드하지 않고 로컬 개발을 하려면 command/args로 npm run dev(tsx src/index.ts)를 대신 실행할 수 있습니다.

동료와 공유하기

이 저장소에는 자격 증명이 포함되어 있지 않습니다. 사용하는 모든 사람은 자신의 PAT/SAT를 생성하여 입력합니다(위의 토큰 생성 참조). 자신의 토큰을 동료와 공유하지 마세요. 대신 이 저장소를 공유하세요:

1. 복제합니다: git clone https://github.com/rrizbaf/cisco-iq-mcp-server.git

2. 설정에 따라 빌드하고 자신의 PAT/SAT, Account ID 및 Region으로 자신만의 .env(또는 mcp.json 항목)를 만듭니다.

3. 각 사용자의 도구 호출은 해당 사용자의 Cisco IQ ID와 권한으로 실행됩니다. 특정 자산/계약에 대한 액세스는 이 서버가 아니라 Cisco IQ 자체에 의해 관리됩니다.

도구 호출 예시

Critical/High 보안 권고가 있는 자산을 최대 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, 스크린샷, 로그 파일, 소스 코드 또는 공유 문서에 넣지 마십시오.

  • 토큰은 만료 전에 교체하고, 노출된 경우 즉시 취소하십시오.

  • 통합에 필요한 최소 권한 역할 및 리소스 그룹 액세스를 사용하십시오(읽기 전용 자동화의 경우 특정 리소스 그룹으로 범위가 지정된 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