io.github.sjk4425/ncloud-gov
MCP server for managing Naver Cloud Platform Government (Ncloud 공공존) infrastructure
Open source Open in the app JSON README (API)
About
MCP server for managing Naver Cloud Platform Government (Ncloud 공공존) infrastructure
Details
- Kind
- MCP servers
- Topic
- Cloud & DevOps
- Publisher
- sjk4425
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.0
- Stars
- 1
- Last push
- 2026-08-28T14:56:36Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:24
- Updated
- 2026-08-29 04:01:24
- Origin id
io.github.sjk4425/ncloud-gov
README
# Ncloud 공공존(Gov) MCP Server
**한국어** | [English](README.en.md)
[](https://github.com/sjk4425/ncloud-gov-mcp-server/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/ncloud-gov-mcp-server)
[](LICENSE)
[Naver Cloud Platform 공공존(Government Cloud)](https://www.gov-ncloud.com) 인프라를 AI 클라이언트에서 자연어로 생성·조회·관리하는 MCP(Model Context Protocol) 서버입니다.
민간존용 [ncloud-mcp-server](https://github.com/sjk4425/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](https://console.gov-ncloud.com))에서 발급한 **API 인증키**(Access Key / Secret Key)
## 설치 & 실행
### 방법 1: npx (권장 - 별도 설치 없이 실행)
npm에 배포된 패키지를 clone·빌드 없이 바로 실행합니다.
```bash
npx -y ncloud-gov-mcp-server
```
### 방법 2: 로컬 빌드 (소스에서 직접)
```bash
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 방식
```json
{
"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"
}
}
}
}
```
### 로컬 빌드 방식
```json
{
"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](.env.example) 참고.
## 공공존과 민간존의 차이
- **도메인**: 대부분의 API Gateway 엔드포인트가 `*.apigw.gov-ntruss.com` 을 사용합니다 (민간존은 `*.apigw.ntruss.com`).
- **인증 방식**: HMAC-SHA256 서명(`x-ncp-apigw-signature-v2` 등)으로 민간존과 **동일**합니다.
- **도메인 예외(기계적 치환 불가)**: 일부 서비스는 gov에서 다른 도메인/경로를 씁니다. 반드시 [공공존 API 문서](https://api-gov.ncloud-docs.com/docs)로 확인:
- 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