Ncloud 공공존(Gov) MCP Server

한국어 | English

통합 패키지로 이전하기

1. 패키지를 ncloud-gov-mcp-server 에서 ncloud-mcp-server 로 바꿉니다.
2. NCLOUD_ZONE=gov 를 추가합니다. 빠뜨리면 민간존 API로 호출되어 인증 오류가 납니다.
3. 나머지 환경 변수는 그대로 둡니다. 공공존 키, NCLOUD_REGION(KR/KRS), NCLOUD_TOOL_GROUPS, NCLOUD_ARCHIVE_PROJECT_ID/NCLOUD_ARCHIVE_DOMAIN_ID 등은 이름과 의미가 같습니다.

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

도구 차이 (0.2.0 → ncloud-mcp-server 2.0.1, NCLOUD_ZONE=gov)

통합 패키지는 공공존에서 도구 약 1,000개를 등록합니다(0.2.0은 약 900개). 0.2.0의 도구 대부분은 이름이 같고, 아래 30개만 다릅니다.

이름이 바뀐 도구 (9개)

제공하지 않는 도구 (21개)

파라미터 변경: Cache, Search Engine Service, Cloud Data Streaming Service, Cloud Insight, Container Registry, KMS 등의 도구 약 80개는 공식 API 가이드에 맞게 파라미터가 바뀌었습니다. AI 클라이언트는 도구 스키마를 자동으로 읽으므로 대개 신경 쓸 필요가 없습니다. 도구 이름과 파라미터를 직접 적어 둔 스크립트나 프롬프트만 확인하세요.

통합 패키지의 공공존 지원은 공공존 API 가이드와 단위 테스트로 검증되었습니다. 실제 공공존 계정으로는 아직 테스트하지 않았습니다. 문제가 있으면 ncloud-mcp-server 이슈로 알려 주세요.

아래는 0.2.x 기준 문서입니다(보관용).

Naver Cloud Platform 공공존(Government Cloud) 인프라를 AI 클라이언트에서 자연어로 생성·조회·관리하는 MCP(Model Context Protocol) 서버입니다.

민간존용 ncloud-mcp-server 를 기반으로 파생한 공공존 전용 프로젝트로, API Gateway 도메인이 *.apigw.gov-ntruss.com 을 사용하도록 구성되어 있습니다. 현재 13개 그룹 · 약 877개 도구를 제공합니다.

지원 서비스

일부 서비스는 관리·모니터링 중심으로 핵심 엔드포인트만 우선 제공합니다(예: VOD Station, Sub Account IAM 전체 범위).

요구 사항

• Node.js 20 이상
• 공공존 콘솔(console.gov-ncloud.com)에서 발급한 API 인증키(Access Key / Secret Key)

설치 & 실행

방법 1: npx (권장 - 별도 설치 없이 실행)

npm에 배포된 패키지를 clone·빌드 없이 바로 실행합니다.

npx -y ncloud-gov-mcp-server

방법 2: 로컬 빌드 (소스에서 직접)

git clone https://github.com/sjk4425/ncloud-gov-mcp-server.git
cd ncloud-gov-mcp-server
npm install
npm run build   # dist/ 생성 (prepare 훅으로 install 시 자동 실행)

MCP 클라이언트 설정 예시

npx 방식

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

로컬 빌드 방식

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

도구 그룹 선택 & 동적 로딩

NCLOUD_TOOL_GROUPS 환경 변수로 로딩할 그룹을 제어합니다. 모든 도구를 한꺼번에 올리면 컨텍스트가 커지므로, 필요한 그룹만 선택하거나 런타임에 확장할 수 있습니다.

동적 그룹 (dynamic)

NCLOUD_TOOL_GROUPS=dynamic 으로 켜면 두 개의 메타 도구가 노출됩니다:

• ncloud_list_tool_groups — 그룹 목록·서비스·도구 수·상태(enabled / available / blocked) 조회
• ncloud_enable_tool_group — 원하는 그룹을 세션 중 즉시 로딩 (예: 스토리지 작업 요청 시 storage 그룹 활성화)

시작 시에는 코어 그룹만 올려 도구 수를 줄이고, AI가 필요한 서비스를 만나면 해당 그룹만 켜서 컨텍스트를 절약합니다. 그룹 활성화 시 발생하는 다량의 tools/list_changed 통지는 1회로 합쳐 전송됩니다.

보안 경계: -database 처럼 운영자가 명시적으로 제외한 그룹은 dynamic 모드에서도 런타임 활성화가 거부됩니다.

환경 변수

전체 목록은 .env.example 참고.

공공존과 민간존의 차이

• 도메인: 대부분의 API Gateway 엔드포인트가 *.apigw.gov-ntruss.com 을 사용합니다 (민간존은 *.apigw.ntruss.com).
• 인증 방식: HMAC-SHA256 서명(x-ncp-apigw-signature-v2 등)으로 민간존과 동일합니다.
• 도메인 예외(기계적 치환 불가): 일부 서비스는 gov에서 다른 도메인/경로를 씁니다. 반드시 공공존 API 문서로 확인:
  • Container Registry: gov-ncr.apigw.gov-ntruss.com (경로 /ncr/{kr|krs}/v2/)
  • Object Storage: {kr|krs}.object.gov-ncloudstorage.com (S3 호환 · AWS SigV4 · 서명 리전 gov-standard/gov2-standard)
  • Archive Storage: kr.archive.gov-ncloudstorage.com (OpenStack Swift · Keystone v3)
  • Private CA: privateca.apigw.gov-ntruss.com (민간존 pca 아님)
  • KMS v2.0: ocapi.gov-ncloud.com (apigw 게이트웨이 아님)
  • VOD Station: vod-station.apigw.gov-ntruss.com (하이픈)
  • NKS / Search Engine / Cloud Data Streaming: 남부권(KRS)은 경로 prefix가 다름 (krs-v2 등)
• 제공 서비스: 공공존은 격리망 특성상 일부 서비스만 제공됩니다. 서비스 추가 전 공공존 API 문서에서 제공 여부를 확인하세요.

검증 상태

• 빌드 & 등록: tsc 빌드 + 단위 테스트 통과. MCP 프로토콜 스모크 테스트로 13개 그룹 877개 도구 등록·중복 없음·동적 활성화 동작 확인.
• 실 API 호출: 공공존 계정으로 각 서비스 엔드포인트를 실제 호출한 검증은 미완료 항목이 있습니다.

라이선스

MIT