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 전체 범위).
요구 사항
설치 & 실행
방법 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
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