ncloud-gov

Ncloud 공공존(Gov) MCP Server

한국어 | English

Warning

이 패키지는 지원이 중단되었습니다. 공공존 지원은 ncloud-mcp-server 2.0+ 에 통합되었습니다. 이 패키지는 민간존·공공존·금융존을 하나로 지원합니다. ncloud-gov-mcp-server 0.2.x는 설치·실행이 계속 되지만, 앞으로 기능 추가와 API 변경 대응은 통합 패키지에서만 합니다.

통합 패키지로 이전하기

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개)

0.2.0	ncloud-mcp-server
ncloud_nks_list_addon_configs	ncloud_nks_list_available_addons
ncloud_nks_get_addon_config	ncloud_nks_get_available_addon
ncloud_nks_get_addon_config_version	ncloud_nks_get_available_addon_version
ncloud_nks_install_cluster_addon	ncloud_nks_install_addons
ncloud_nks_update_cluster_addon	ncloud_nks_update_addon
ncloud_nks_delete_cluster_addon	ncloud_nks_delete_addon
ncloud_change_fabric_cluster_name / ncloud_change_fabric_cluster_description	ncloud_update_fabric_cluster (하나로 통합)
ncloud_cdss_restart_cmak	ncloud_cdss_restart_cmak_service

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

0.2.0 도구	이유
CDN+ ncloud_cdnplus_* 5개, Global CDN ncloud_globalcdn_* 5개	2026-12-31 서비스 종료 예정(신규 생성 불가). 대신 Global Edge(ncloud_edge_*)를 제공
SES ncloud_ses_get_cluster_detail, get_server_generations, get_server_specs, get_cluster_server_images, get_subnet_list_g3, create_cluster_g3, change_disk_size	공공존 API 가이드에 없는 오퍼레이션(민간존 전용 G3/KVM 계열)
CDSS ncloud_cdss_get_server_generations, get_server_spec_list, get_cluster_server_images	공공존 API 가이드에 없는 오퍼레이션(민간존 전용 G3 계열)
ncloud_nks_reset_kubeconfig	공공존 API 가이드에 없는 오퍼레이션

파라미터 변경: 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개 도구를 제공합니다.

지원 서비스

그룹 (key)	서비스
common	Region / Zone (always on)
compute	Server, Block Storage, Public IP, Login Key, Init Script, Placement Group, Auto Scaling, ACG, Network Interface, Cloud Functions
network	VPC, Network ACL, NAT Gateway, Route Table, VPC Peering, Load Balancer, Target Group, Global DNS, Global Traffic Manager
database	Cloud DB for MySQL / PostgreSQL / MSSQL / MongoDB / Redis(Cache)
containers	Container Registry (NCR), Kubernetes Service (NKS)
storage	NAS, Object Storage (S3 호환), Archive Storage (OpenStack Swift)
devtools	Source Commit, Source Build, Source Deploy, Source Pipeline
security	Certificate Manager, Private CA, Security Monitoring, KMS (v2.0)
analytics	Cloud Hadoop, Search Engine Service, Cloud Data Streaming Service, Cloud Log Analytics
cdn	CDN+, Global CDN
media	VOD Station, One-Click Multi DRM
governance	Sub Account, Activity Tracer, Cloud Insight, Resource Manager, WMS
billing	List Price, Cost and Usage, Discount (요금·비용·할인 조회)

일부 서비스는 관리·모니터링 중심으로 핵심 엔드포인트만 우선 제공합니다(예: 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 환경 변수로 로딩할 그룹을 제어합니다. 모든 도구를 한꺼번에 올리면 컨텍스트가 커지므로, 필요한 그룹만 선택하거나 런타임에 확장할 수 있습니다.

설정값	동작
(미설정)	전체 ON — 13개 그룹 877개 도구 모두 등록
compute,network	지정한 그룹 + common 만 등록 (잠금 — 런타임 변경 불가)
all,-database	전체에서 특정 그룹 제외. 제외된 그룹은 런타임 활성화도 차단
dynamic	코어 세트(common + compute + network + database)만 시작 + 런타임 확장 허용

동적 그룹 (dynamic)

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

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

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

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

환경 변수

변수	필수	기본값	설명
NCLOUD_ACCESS_KEY	✅	—	공공존 API Access Key
NCLOUD_SECRET_KEY	✅	—	공공존 API Secret Key
NCLOUD_REGION		KR	리전 코드 (KR 수도권 / KRS 남부권)
NCLOUD_API_URL		https://ncloud.apigw.gov-ntruss.com	기본 API Gateway 도메인
NCLOUD_TOOL_GROUPS		(전체 ON)	로딩할 그룹. dynamic = 코어 세트 + 런타임 확장 (위 표 참고)
NCLOUD_ARCHIVE_PROJECT_ID		—	Archive Storage 사용 시 필수 (Keystone project_id). 두 값이 모두 있어야 Archive 도구 등록
NCLOUD_ARCHIVE_DOMAIN_ID		—	Archive Storage 사용 시 필수 (Keystone domain_id)
NCLOUD_LANG		ko	에러 메시지 언어 (en 지정 시 영문)
NCLOUD_TIMEOUT_MS		30000	API 요청 타임아웃(ms)

전체 목록은 .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