Ncloud MCP Server

English

Naver Cloud Platform(Ncloud) 인프라를 AI 어시스턴트에서 직접 관리할 수 있는 Model Context Protocol (MCP) 서버입니다.

주요 기능

Ncloud의 60개 이상 서비스, 1,000개 이상 API 도구를 MCP 프로토콜로 제공합니다.

ℹ️ 각 카테고리는 NCLOUD_TOOL_GROUPS의 그룹 key와 1:1로 대응합니다. 도구 일부만 로딩하려면 아래 도구 그룹 선택 표를 참고하세요.

모든 도구에 MCP 표준 tool annotations(readOnlyHint/destructiveHint/idempotentHint)이 부여되어, 지원 클라이언트에서 조회 도구 자동 승인·파괴적 도구 확인 UX를 적용할 수 있습니다. 파괴적 도구의 confirm 파라미터 게이트는 그대로 유지됩니다(이중 방어).

사전 요구사항

• Node.js 20 이상
• Ncloud API 인증키 (포털에서 발급)

참고 사항

• 이 MCP 서버는 Ncloud 민간존(Public) 기준으로 구현되었습니다. 금융존/공공존 환경에서는 API 엔드포인트가 다를 수 있습니다.
• API 스펙은 Ncloud API 공식 문서를 기반으로 작성되었습니다.
• 한국(KR) 리전 위주로 테스트되었습니다. 다른 리전에서는 일부 API의 동작이 다를 수 있습니다.

설치

npx (권장 — 설치 불필요)

별도 설치 없이 npx로 바로 실행할 수 있습니다:

npx -y ncloud-mcp-server

MCP 클라이언트 설정 방법은 아래 MCP 클라이언트 설정 섹션을 참고하세요.

소스에서 빌드

# 저장소 클론
git clone https://github.com/sjk4425/ncloud-mcp-server.git
cd ncloud-mcp-server

# 의존성 설치 및 빌드
npm install
npm run build

환경 변수

MCP 클라이언트 설정

npx 사용 (권장)

mcp.json (또는 해당 클라이언트의 MCP 설정 파일)에 추가:

{
  "mcpServers": {
    "ncloud": {
      "command": "npx",
      "args": ["-y", "ncloud-mcp-server"],
      "env": {
        "NCLOUD_ACCESS_KEY": "your-access-key",
        "NCLOUD_SECRET_KEY": "your-secret-key",
        "NCLOUD_REGION": "KR"
      }
    }
  }
}

소스 빌드 사용

{
  "mcpServers": {
    "ncloud": {
      "command": "node",
      "args": ["path/to/ncloud-mcp-server/dist/index.js"],
      "env": {
        "NCLOUD_ACCESS_KEY": "your-access-key",
        "NCLOUD_SECRET_KEY": "your-secret-key",
        "NCLOUD_REGION": "KR"
      }
    }
  }
}

도구 그룹 선택 (선택)

기본 설정만으로 전체 도구(약 1,000개)가 모두 동작합니다. 그냥 다 쓰고 싶다면 이 변수를 설정하지 마세요 — 미설정이 곧 "전체 ON"이며 기존과 동일하게 동작합니다. 아래는 시작 컨텍스트를 가볍게 하거나(권장: dynamic), 도구를 일부만 켜고 싶을 때만 보면 됩니다.

왜 필요한가요? 전체 ON이면 도구 정의만으로 세션 컨텍스트를 크게 점유합니다(tools/list ≈ 694KB / 약 177k 토큰). NCLOUD_TOOL_GROUPS로 필요한 그룹만 켜면 AI가 한 번에 보는 도구 수가 줄어 토큰 비용이 절감되고 도구 선택 정확도가 올라갑니다. 설정은 mcp.json의 env에 NCLOUD_TOOL_GROUPS 한 줄을 추가하면 됩니다. (common은 Region/Zone 공통 도구라 항상 자동 포함)

한눈에 — 어떤 값을 쓸까

핵심 규칙: dynamic 키워드가 있을 때만 세션 중 그룹 확장이 켜집니다. dynamic 없이 그룹을 나열하면(예: compute,network) "딱 이것만"을 의미하는 잠금이 되고, all/미설정은 이미 전부 켜져 있어 확장이 무의미합니다(더 켤 그룹 없음). 사용 가능한 전체 그룹 key 목록은 아래 세부 제어의 표를 참조하세요.

권장: dynamic (동적 그룹)

전체를 다 켜는 대신 핵심 그룹만 켠 채 가볍게 시작하고, AI가 다른 서비스를 요청받으면 서버 재시작 없이 세션 중에 해당 그룹을 자동으로 켭니다.

{
  "mcpServers": {
    "ncloud": {
      "command": "npx",
      "args": ["-y", "ncloud-mcp-server"],
      "env": {
        "NCLOUD_ACCESS_KEY": "your-access-key",
        "NCLOUD_SECRET_KEY": "your-secret-key",
        "NCLOUD_REGION": "KR",
        "NCLOUD_TOOL_GROUPS": "dynamic"
      }
    }
  }
}

한 줄 요약: dynamic = "확장 모드 ON + 핵심 세트로 가볍게 시작". 안 쓰는 그룹은 처음에 안 올려 토큰을 아끼고, 필요할 때만 자동으로 켭니다.

• 시작 ON: common + compute + network + database (약 367개 도구 / 약 65k 토큰 — 전체 대비 63% 절감)
• AI는 항상 켜져 있는 메타 도구로 나머지 그룹에 도달합니다:
  • ncloud_list_tool_groups — 14개 그룹의 서비스·도구 수·현재 ON/OFF 조회
  • ncloud_enable_tool_group — 그룹을 런타임에 활성화 (멱등)

dynamic vs all — 무엇이 다른가

둘 다 결국 모든 그룹을 쓸 수 있지만, dynamic은 "처음엔 핵심만, 나머지는 쓸 때" 방식이라 시작 컨텍스트가 가볍습니다. 이 절감이 dynamic의 존재 이유입니다.

동작 흐름 (예: Live Station 요청)

1. 서버 시작: 핵심 그룹 + 메타 도구만 ON
2. 사용자: "Live Station 채널 목록 보여줘"
3. AI: 카탈로그에서 media 그룹 확인 → ncloud_enable_tool_group("media")
4. 서버: media 도구 등록 + tools/list_changed 통지 → 클라이언트 도구 목록 갱신
5. AI: 새로 나타난 Live Station 도구 호출 → 작업 계속

• 켜진 상태는 세션 동안만 유지됩니다(다음 세션은 기본값으로 리셋).
• dynamic에 그룹 키를 더하면 그 그룹은 "시작 즉시 ON"입니다(나중에 동적으로 붙는 게 아님). 예: dynamic,analytics는 핵심 세트 + analytics를 처음부터 켜고 나머지만 확장 대상으로 둡니다. 매일 쓰는 그룹은 이렇게 적어두면 enable 호출 없이 바로 씁니다.

클라이언트 호환성 — 동적 추가된 도구가 즉시 나타나려면 클라이언트가 tools/list_changed 통지를 지원해야 합니다.

💡 표에 없거나 "미검증"인 클라이언트는 30초만에 직접 확인할 수 있습니다. NCLOUD_TOOL_GROUPS=dynamic으로 설정 후 AI에게 *"media 그룹 켜고 Live Station 채널 목록 보여줘"*라고 요청 → 새 도구가 그 세션에서 호출되면 지원, AI가 도구를 못 찾으면 미지원이니 그룹을 미리 나열하는 방식으로 쓰면 됩니다.

list_changed 미지원 클라이언트(예: Kiro)에서는 dynamic의 세션 중 자동 확장이 동작하지 않습니다. enable은 되지만 새 도구가 도구 목록에 안 떠 호출할 수 없습니다. 이 경우 자주 쓰는 그룹을 미리 나열하세요 — 예: dynamic,governance,media처럼 시작부터 켜거나, 명시 리스트(compute,network,...)·all로 설정. (enable 응답도 같은 폴백을 안내합니다: NCLOUD_TOOL_GROUPS에 그룹을 추가하고 재시작.) 폴백 시 기존과 동일한 경험으로 회귀하므로 악화는 없습니다.

ℹ️ 권한 경계: MCP 도구가 노출된다고 권한이 부여되는 것은 아닙니다. Ncloud 측 실제 권한은 Access Key의 Sub Account 권한이 최종 경계입니다. 동적 로딩은 confirm 게이트·destructive 경고 등 기존 안전장치를 우회하지 않습니다.

세부 제어 — 특정 그룹만 켜기 / 잠금

dynamic 없이 그룹 key를 쉼표로 나열하면 그 그룹만 켜지고 런타임 확장이 잠깁니다(엄격 운영·최소 권한 환경용). 예: "NCLOUD_TOOL_GROUPS": "compute,network,billing". all,-billing처럼 -로 특정 그룹을 제외할 수도 있으며, 제외된 그룹은 동적 enable도 거부됩니다(운영자 보안 경계).

서버 시작 시 어떤 그룹이 로딩됐는지 로그로 확인할 수 있습니다: ncloud-mcp-server: 4개 그룹 등록 (common, compute, network, billing) 잘못된 key는 무시되고 경고만 출력됩니다.

그룹 key → 포함 서비스

ℹ️ 그룹 key 변경 안내 (v1.2.0): integration → application으로 이름이 바뀌었고, global은 cdn(Global Edge)과 network(Global DNS/Traffic Manager)로 나뉘었습니다. 옛 key는 자동 호환되지 않으니 새 key로 변경하세요(옛 key를 지정하면 서버가 안내 메시지를 출력하고 무시합니다).

사용 예시

MCP 클라이언트에서 자연어로 Ncloud 인프라를 관리할 수 있습니다:

"현재 서버 목록을 보여줘"
"KR-2 존에 Ubuntu 서버를 하나 만들어줘"
"my-vpc의 서브넷 목록을 조회해줘"
"Cloud DB for MySQL 인스턴스 상태를 확인해줘"
"Object Storage에 새 버킷을 만들어줘"
"로드밸런서에 연결된 타겟 그룹을 확인해줘"
"Cloud Insight에서 CPU 사용률 상위 서버를 조회해줘"

지원 리전

참고: 미국 서부(USWN), 독일(DEN) 리전은 Classic 환경만 지원되어 VPC 기반인 본 MCP 서버에서는 사용이 제한됩니다.

문제 해결

프로젝트 구조

ncloud-mcp-server/
├── src/
│   ├── index.ts              # MCP 서버 엔트리포인트 (stdio transport)
│   ├── auth/
│   │   └── signature.ts      # HMAC-SHA256 서명 생성
│   ├── client/
│   │   ├── ncloud-client.ts  # Ncloud API HTTP 클라이언트
│   │   ├── s3-compatible-client.ts   # Object Storage (S3 호환)
│   │   └── swift-compatible-client.ts # Archive Storage (Swift 호환)
│   └── tools/                # 서비스별 MCP 도구 (63개 파일)
│       ├── compute-server.ts
│       ├── vpc.ts
│       ├── cloud-insight.ts
│       └── ...
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md

개발

# 빌드
npm run build

# 테스트
npm test

# 타입 체크
npx tsc --noEmit

기여

이슈와 PR을 환영합니다. 기여 시 다음을 참고해주세요:

1. Fork 후 feature 브랜치에서 작업
2. npm run build로 빌드 확인
3. npm test로 테스트 통과 확인
4. PR 제출

라이선스

MIT