Ncloud

Ncloud MCP Server

English

Naver Cloud Platform(Ncloud) 인프라를 AI 어시스턴트에서 직접 관리할 수 있는 Model Context Protocol (MCP) 서버입니다.

민간존(Public)·공공존(Government)·금융존(Financial)을 하나의 서버로 지원합니다. NCLOUD_ZONE=gov 또는 NCLOUD_ZONE=fin 한 줄로 해당 존의 API 게이트웨이·리전·서비스 카탈로그로 전환되며, 미설정 시 민간존입니다 → 존 선택.

주요 기능

Ncloud의 60개 이상 서비스, 1,000개 이상 API 도구를 MCP 프로토콜로 제공합니다.

ℹ️ 각 카테고리는 NCLOUD_TOOL_GROUPS의 그룹 key와 1:1로 대응합니다. 도구 일부만 로딩하려면 아래 도구 그룹 선택 표를 참고하세요.

🅿 = 민간존 전용(공공존·금융존 API 가이드에 없음) · ⓖ = 공공존 미제공 · ⓕ = 금융존 미제공. 존별 세부 차이는 존 선택의 표를 참고하세요.

모든 도구에 MCP 표준 tool annotations(readOnlyHint/destructiveHint/idempotentHint)이 부여되어, 지원 클라이언트에서 조회 도구 자동 승인·파괴적 도구 확인 UX를 적용할 수 있습니다. 파괴적 도구의 confirm 파라미터 게이트는 그대로 유지됩니다(이중 방어).

사전 요구사항

• Node.js 20 이상
• Ncloud API 인증키 (포털에서 발급)

참고 사항

• 민간존(Public)·공공존(Government)·금융존(Financial) 을 지원합니다. NCLOUD_ZONE으로 선택하며, 인증키는 반드시 해당 존 콘솔에서 발급한 것을 써야 합니다.
• API 스펙은 민간존 API 가이드, 공공존 API 가이드, 금융존 API 가이드를 기반으로 작성되었으며, 존별 엔드포인트·리전·오퍼레이션 차이는 세 가이드를 대조해 반영했습니다.
• 민간존 한국(KR) 리전 위주로 실계정 테스트되었습니다. 공공존·금융존 지원은 각 존의 공식 API 가이드 대조와 단위 테스트로 검증되었으며 아직 실계정으로 확인되지 않았습니다 — 공공존·금융존에서 문제가 있으면 이슈로 알려 주세요. 다른 리전·존에서는 일부 API의 동작이 다를 수 있습니다.

설치

npx (권장 — 설치 불필요)

별도 설치 없이 npx로 바로 실행할 수 있습니다:

npx -y ncloud-mcp-server

MCP 클라이언트 설정 방법은 아래 MCP 클라이언트 설정 섹션을 참고하세요.

소스에서 빌드

# 저장소 클론

git clone https://github.com/sjk4425/ncloud-mcp-server.git cd ncloud-mcp-server

의존성 설치 및 빌드

npm install npm run build

환경 변수

존 선택 (민간존 / 공공존 / 금융존)

하나의 패키지로 세 존을 지원합니다. NCLOUD_ZONE만 바꾸면 API 게이트웨이 도메인, 리전 카탈로그, 존별 서비스 카탈로그, 일부 서비스의 API 버전·경로·필드 차이까지 서버가 알아서 맞춥니다. 도구 이름과 파라미터는 세 존에서 동일하므로 프롬프트를 바꿀 필요가 없습니다.

도구 수는 NCLOUD_ARCHIVE_PROJECT_ID/NCLOUD_ARCHIVE_DOMAIN_ID 미설정 기준입니다. 설정하면 Archive Storage 도구 10개가 민간존·공공존에 추가됩니다.

⚠️ 인증키는 존별로 별개입니다. 민간존 키로 공공존·금융존을 호출하면(또는 그 반대) 인증 오류가 납니다. NCLOUD_ZONE에 pub/gov/fin 외의 값을 주면 다른 존으로 조용히 가지 않도록 서버가 시작 시 종료합니다.

🔑 계정·키 관련 주의 (2.0.0)

- Certificate Manager 2.0 (ncloud_cm2_*, 민간존)은 메인 계정 Access Key로만 호출됩니다(Ncloud 기술지원 확인). 서브 계정 키는 2.0 엔드포인트가 HTTP 403으로 거부하며, 이때 서버는 호출자 정보와 함께 안내문을 돌려주고 조회·외부 인증서 등록은 어떤 키로든 되는 1.0 도구(ncloud_list_certificates, ncloud_register_external_certificate)를 안내합니다.

- Secret Manager (ncloud_secret_*, 민간존)은 시크릿을 암호화한 KMS 키 종류에 따라 호스트가 다릅니다. 모든 도구의 keyIsolation 파라미터로 고릅니다 — global(기본, secretmanager.apigw.ntruss.com) / regional(KMS 리전 격리 키, ocapi-kr.ncloud.com/secretmanager; 일본 리전은 격리 키만). 격리 키 호스트는 서버 시작 시 리전(NCLOUD_REGION)으로 정해집니다.

- Cloud DB Serverless (ncloud_serverless_*, 민간존)도 메인 계정 Access Key로만 호출됩니다. 서브 계정 키는 API가 HTTP 403 sub account is not supported yet로 거부하며(2026-10-02 재확인, NCP_ADMINISTRATOR 서브 계정), 서버는 그 403에 메인 계정 키를 쓰라는 안내를 덧붙입니다. 같은 키로 Cloud DB for MySQL 등 다른 DB 도구는 정상 동작합니다.

- 현재 키가 메인 계정인지 서브 계정인지는 ncloud_get_caller_identity(STS, 세 존)로 확인할 수 있습니다.

공공존 설정 예시

{

"mcpServers": { "ncloud-gov": { "command": "npx", "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" } } } }

금융존은 "NCLOUD_ZONE": "fin", "NCLOUD_REGION": "FKR"(생략 가능 — 금융존 기본값)에 금융존 콘솔에서 발급한 키를 넣으면 됩니다. 여러 존을 동시에 쓰려면 위처럼 이름이 다른 서버 항목을 여러 개(ncloud, ncloud-gov, ncloud-fin) 등록하면 됩니다.

존별 차이 (공식 가이드 대조, 2026-09-30 기준)

해당 존에서 제공되지 않는 도구는 등록 자체가 되지 않으므로 도구 목록에 나타나지 않습니다. ncloud_get_current_region으로 현재 서버가 묶인 존과 사용 가능한 리전을 확인할 수 있습니다.

MCP 클라이언트 설정

npx 사용 (권장)

mcp.json (또는 해당 클라이언트의 MCP 설정 파일)에 추가:

{

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

소스 빌드 사용

{

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

도구 그룹 선택 (선택)

기본 설정만으로 전체 도구(약 1,000개)가 모두 동작합니다. 그냥 다 쓰고 싶다면 이 변수를 설정하지 마세요 — 미설정이 곧 "전체 ON"이며 기존과 동일하게 동작합니다. 아래는 *시작 컨텍스트를 가볍게 하거나(권장: dynamic), 도구를 일부만 켜고 싶을 때*만 보면 됩니다.

왜 필요한가요? 전체 ON이면 도구 정의만으로 세션 컨텍스트를 크게 점유합니다(tools/list ≈ 694KB / 약 177k 토큰). NCLOUD_TOOL_GROUPS로 필요한 그룹만 켜면 AI가 한 번에 보는 도구 수가 줄어 토큰 비용이 절감되고 도구