Ncloud 공공존(Gov) MCP Server

한국어 | English

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