Ncloud MCP Server

Name: Ncloud MCP Server
Author: sjk4425

ローカル

github.com/sjk4425開発ツール2今日更新

リポジトリ

Ncloud MCP Server について

Ncloud MCP Serverは、AIアシスタントからNaver Cloud Platformのコンピューティング、ネットワーク、データベース、ストレージなどを管理するサーバーです。1つのサーバーで民間・公共・金融ゾーンに対応し、ツールグループを選択できます。

主な機能

0160以上のサービスにわたる1,000以上のAPIツール
02民間・公共・金融ゾーンへの対応
03ツールグループの選択と動的な有効化
04MCPツールアノテーションと確認ゲート
05クラウドインフラの参照と管理

活用シーン

01コンピューティングやネットワークリソースの確認・管理
02Ncloudのデータベースやストレージの利用
03デプロイ先のゾーンに応じたサービス選択
04セッションに必要なツールグループだけを読み込む

MCP 対応

Naver Cloud PlatformのAPIをMCPツールとしてクライアントに公開し、インフラ管理や請求機能を提供します。ツールグループは起動時に選択でき、セッション中にも有効化できます。

#mcp #ncloud #naver-cloud #cloud #infrastructure #ai #navercloudplatform #ncp

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "ncloud": {
      "command": "npx",
      "args": [
        "-y",
        "ncloud-mcp-server"
      ],
      "env": {
        "NCLOUD_ACCESS_KEY": "<NCLOUD_ACCESS_KEY>",
        "NCLOUD_SECRET_KEY": "<NCLOUD_SECRET_KEY>",
        "NCLOUD_ZONE": "<NCLOUD_ZONE>",
        "NCLOUD_REGION": "<NCLOUD_REGION>",
        "NCLOUD_TOOL_GROUPS": "<NCLOUD_TOOL_GROUPS>",
        "NCLOUD_RESPONSE_PRUNE": "<NCLOUD_RESPONSE_PRUNE>",
        "NCLOUD_TIMEOUT_MS": "<NCLOUD_TIMEOUT_MS>",
        "NCLOUD_LANG": "<NCLOUD_LANG>",
        "NCLOUD_RESPONSE_MAXBYTES": "<NCLOUD_RESPONSE_MAXBYTES>"
      }
    }
  }
}

起動コマンドnpx -y ncloud-mcp-server

設定が必要な環境変数

NCLOUD_ACCESS_KEYシークレットNcloud API Access Key

NCLOUD_SECRET_KEYシークレットNcloud API Secret Key

NCLOUD_ZONEZone: 'pub' (default, Public zone), 'gov' (Government zone) or 'fin' (Financial zone). Selects the API gateways, regions and service catalogue; credentials must be issued by that zone's console. Any other value aborts startup.

NCLOUD_REGIONNcloud region code. Public zone: KR, JPN, SGN, USWN, DEN. Government zone: KR (KR-CENTRAL), KRS (KR-SOUTH). Financial zone: FKR. Default KR (FKR in the Financial zone).

NCLOUD_TOOL_GROUPSComma-separated tool groups to load at startup, e.g. 'compute,network,billing' or 'all,-billing'. Unset = all groups. Include the 'dynamic' keyword to start with the core set (common+compute+network+database) AND allow mid-session expansion via the ncloud_enable_tool_group meta tool; without 'dynamic', the listed groups are locked (no runtime expansion). A '-'-excluded group is also refused for dynamic enable. common is always on.

NCLOUD_RESPONSE_PRUNESet to '1' to strip empty values (null/""/[]/{}) from responses globally.

NCLOUD_TIMEOUT_MSAPI request timeout in milliseconds (default 30000). HTTP 429 is always auto-retried up to 2 times; read-only query tools also retry 503/504 and network errors.

NCLOUD_LANGLanguage for client error messages: 'en' for English, otherwise/unset is Korean (default).

NCLOUD_RESPONSE_MAXBYTESOpt-in response-size guard for read-only tools. When set to a positive byte threshold, large read-only responses are truncated item-by-item to stay under it, adding 'truncated'/'suggestedPageSize' recovery hints. Unset/0 = guard off (response shape unchanged).

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

npmncloud-mcp-server2.1.0stdio

ツール

200

掲載時のツール一覧 · 3 週間前に更新

このツールにパラメーターはありません。

詳細

Ncloud MCP サーバー

英語

Naver Cloud Platform（Ncloud）インフラをAIアシスタントから直接管理できる、Model Context Protocol (MCP) サーバーです。

民間ゾーン（Public）・公共ゾーン（Government）・金融ゾーン（Financial）を1つのサーバーでサポートします。NCLOUD_ZONE=gov または NCLOUD_ZONE=fin の1行で、該当ゾーンのAPIゲートウェイ・リージョン・サービスカタログに切り替わります。未設定の場合は民間ゾーンです → ゾーンの選択。

主な機能

Ncloudの60以上のサービス、1,000以上のAPIツールをMCPプロトコルで提供します。

カテゴリ	サービス
コンピューティング	Server、Block Storage、Snapshot、Public IP、Init Script、Login Key、Placement Group、Fabric Cluster ⓕ、Auto Scaling、Cloud Functions
ネットワーキング	VPC、Subnet、ACG、Network ACL、NAT Gateway、Route Table、VPC Peering、Network Interface、Load Balancer、Target Group、Global DNS、Global Traffic Manager ⓕ
データベース	Cloud DB for MySQL、PostgreSQL、MSSQL、MongoDB、Cache (Redis/Valkey)、Cloud DB Serverless (MySQL) 🅿
ストレージ	Object Storage（S3互換）、Ncloud Storage（S3互換）ⓕ、NAS、Archive Storage（Swift互換）ⓕ
コンテナ	Ncloud Kubernetes Service (NKS)、Container Registry
セキュリティ	Certificate Manager（2.0は民間ゾーン専用・メインアカウントキーが必要）、Private CA ⓕ、KMS（金融ゾーンでは暗号化・復号の6種類のみ）、Security Monitoring ⓕ、Secret Manager 🅿
モニタリング	Cloud Insight、Log Analytics
管理とガバナンス	Activity Tracer、Cloud Advisor 🅿、Resource Manager、Sub Account、Web service Monitoring System (WMS)、STS（呼び出し元の識別）
開発ツール	SourceCommit、SourceBuild、SourceDeploy、SourcePipeline
分析	Search Engine Service、Cloud Hadoop、Cloud Data Streaming Service、Data Stream 🅿、Data Catalog 🅿、Data Forest 🅿、Data Flow 🅿、Data Query 🅿、Datafence 🅿、Cloud Data Box 🅿
メディア	VOD Station、Live Station ⓖ、One Click Multi DRM ⓕ
コンテンツ配信（CDN）	Global Edge ⓕ、CDN+（金融ゾーン専用）
アプリケーション	API Gateway、SENS（SMS/通知トーク/ブランドメッセージ/Mail 🅿、プロジェクト）、Cloud Outbound Mailer（民間ゾーン：レガシーは「27-12」まで／公共ゾーン・金融ゾーン：正式版）
請求	Billing（料金・価格の確認、コスト・使用量、割引）

ℹ️ 各カテゴリは NCLOUD_TOOL_GROUPS のグループキーに1対1で対応します。一部のツールのみを読み込む場合は、以下のツールグループの選択表を参照してください。 🅿 = 民間ゾーン専用（公共ゾーン・金融ゾーンのAPIガイドには記載なし） · ⓖ = 公共ゾーンでは提供なし · ⓕ = 金融ゾーンでは提供なし。ゾーンごとの詳細な違いはゾーンの選択の表を参照してください。

すべてのツールにMCP標準のツールアノテーション（readOnlyHint/destructiveHint/idempotentHint）が付与されているため、対応クライアントでは参照ツールの自動承認や、破壊的なツールの確認UXを適用できます。破壊的なツールの confirm パラメーターによるゲートはそのまま維持されます（二重防御）。

前提条件

Node.js 20以上
Ncloud API認証キー（ポータルで発行）

注意事項

**民間ゾーン（Public）・公共ゾーン（Government）・金融ゾーン（Financial）**をサポートします。NCLOUD_ZONE で選択し、認証キーには必ず該当ゾーンのコンソールで発行したものを使用してください。
API仕様は民間ゾーンAPIガイド、公共ゾーンAPIガイド、金融ゾーンAPIガイドに基づいており、ゾーンごとのエンドポイント・リージョン・オペレーションの違いは、3つのガイドを照合して反映しています。
民間ゾーンの韓国（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_ACCESS_KEY`	✅	Ncloud API Access Key	-
`NCLOUD_SECRET_KEY`	✅	Ncloud API Secret Key	-
`NCLOUD_ZONE`	-	ゾーンを選択します。`pub`（民間ゾーン）、`gov`（公共ゾーン）、`fin`（金融ゾーン）。無効な値の場合は起動を中止します（詳しくは下記のゾーンの選択を参照）	`pub`
`NCLOUD_REGION`	-	リージョンコード。民間ゾーンは`KR`/`JPN`/`SGN`/`USWN`/`DEN`、公共ゾーンは`KR`（首都圏）/`KRS`（南部圏）、金融ゾーンは`FKR`	`KR`（金融ゾーンは`FKR`）
`NCLOUD_API_URL`	-	デフォルトのAPIゲートウェイのオーバーライド（ゾーンのデフォルト値を上書き）	民間ゾーン `https://ncloud.apigw.ntruss.com` / 公共ゾーン `https://ncloud.apigw.gov-ntruss.com` / 金融ゾーン `https://fin-ncloud.apigw.fin-ntruss.com`
`NCLOUD_ARCHIVE_PROJECT_ID`	-	Archive Storage プロジェクト ID	-
`NCLOUD_ARCHIVE_DOMAIN_ID`	-	Archive Storage ドメイン ID	-
`NCLOUD_SENS_SERVICE_ID`	-	SENS チャネル共通のデフォルト serviceId（NRN、例 `ncp:sms:kr:…`）。チャネル別の変数 `NCLOUD_SENS_SMS_SERVICE_ID` / `NCLOUD_SENS_ALIMTALK_SERVICE_ID` / `NCLOUD_SENS_BRANDMESSAGE_SERVICE_ID`（未設定の場合は通知トークの値を使用）/ `NCLOUD_SENS_MAIL_SERVICE_ID` が優先されます。すべての SENS ツールは `serviceId` パラメーターで呼び出しごとにオーバーライドでき、NRN は `ncloud_sens_list_projects` で確認できます	-
`NCLOUD_STORAGE_ADDRESSING`	-	Ncloud Storage（`ncloud_ncs_*`）バケットのアドレス方式。デフォルトは公式ドキュメントの virtual-hosted（`https://{bucket}.kr.ncloudstorage.com/`）です。`path` を指定すると従来方式（`https://kr.ncloudstorage.com/{bucket}/`）に戻ります。Ncloud Storage は KR の単一リージョンのため、`NCLOUD_REGION` には依存しません	virtual-hosted
`NCLOUD_TOOL_GROUPS`	-	起動時に読み込むツールグループを選択します。未設定の場合はすべて ON です。`dynamic` を含めるとコアグループのみを有効にし、セッション中の拡張を許可します（それ以外の値では固定されます）（詳しくは下記のツールグループの選択（選択）を参照）	全体
`NCLOUD_RESPONSE_PRUNE`	-	`1` の場合、応答から空の値（`null`/`""`/`[]`/`{}`）を全体的に削除します	`0`
`NCLOUD_TIMEOUT_MS`	-	API リクエストのタイムアウト（ミリ秒）。超過すると呼び出しを中止し、案内メッセージを返します（HTTP 429 は常に最大2回自動再試行し、参照ツールは503/504・ネットワークエラーも再試行します）	`30000`
`NCLOUD_LANG`	-	クライアントのエラーメッセージの言語。`en` の場合は英語、それ以外または未設定の場合は韓国語です	`ko`
`NCLOUD_RESPONSE_MAXBYTES`	-	オプトインの応答サイズガード（バイト）。正の値を設定すると、参照ツールの大きな応答を項目単位で切り詰め、しきい値以下にして `truncated`/`suggestedPageSize` ヒントを付加します。未設定または0の場合はガード OFF（応答を変更しません）	-

ゾーンの選択（民間ゾーン／公共ゾーン／金融ゾーン）

1つのパッケージで3つのゾーンをサポートします。NCLOUD_ZONE を変更するだけで、API ゲートウェイドメイン、リージョンカタログ、ゾーン別サービスカタログ、一部サービスの API バージョン・パス・フィールドの違いまで、サーバーが自動的に調整します。ツール名とパラメーターは3つのゾーンで共通のため、プロンプトを変更する必要はありません。

	民間ゾーン（`pub`、デフォルト）	公共ゾーン（`gov`）	金融ゾーン（`fin`）
認証キーの発行	民間ゾーンコンソール	公共ゾーンコンソール	金融ゾーンコンソール
デフォルトゲートウェイ	`ncloud.apigw.ntruss.com`	`ncloud.apigw.gov-ntruss.com`	`fin-ncloud.apigw.fin-ntruss.com`
リージョン（`NCLOUD_REGION`）	`KR`、`JPN`、`SGN`、`USWN`、`DEN`	`KR`（首都圏）、`KRS`（南部圏）	`FKR`
API ガイド	https://api.ncloud-docs.com/docs/home	https://api-gov.ncloud-docs.com/docs	https://api-fin.ncloud-docs.com/docs/api-overview
ツール数（全グループ）	1,300	1,007	862

ツール数は 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、3つのゾーン）で確認できます。

公共ゾーンの設定例

{
  "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 時点）

区分	内容
民間ゾーン専用サービス	Cloud DB Serverless、Cloud Advisor、Live Station（金融ゾーンでも提供）、Data Stream/Catalog/Forest/Flow/Query、Datafence、Cloud Data Box、Secret Manager、Certificate Manager 2.0、SENS Mail チャネル
民間ゾーン専用オペレーション	LB リスナー証明書（SNI）3 種（金融ゾーンでも提供）、NKS kubeconfig の再発行、VOD Station チャネルの変更（金融ゾーンでも提供）、DRM ポリシーの複製、SES/CDSS の KVM（G3）作成・スペック照会関連、KMS キー作成の `protectionType`
公共ゾーン専用オペレーション	Cloud DB for Cache のユーザー（ACL）管理 4 種、Certificate Manager のプライベート証明書発行（`issuePrivate`）、Cloud Outbound Mailer の送信・照会 5 種（金融ゾーンでも提供。民間ゾーンでは SENS Mail で代替）
金融ゾーンで提供されないサービス	Global Traffic Manager、Ncloud Storage、Archive Storage、Cloud DB Serverless、Fabric Cluster、NKS Add-on Manager、Cloud Advisor、Data*、One Click Multi DRM、Global Edge（金融ゾーンの `cdn` グループは CDN+ 5 種）、Private CA、Security Monitoring、KMS API 2.0（キー管理・ACL・トークン）
金融ゾーン専用オペレーション	Cloud Insight Metric Export 6 種、Cloud Log Analytics のサーバーログ収集解除（`ncloud_delete_server_log_collection`）
同じサービス、異なる API	Cloud Functions：民間ゾーン・金融ゾーンの API v2.1（`/ncf/api/v2`。金融ゾーンは VPC 専用で、`platform` クエリなし）／公共ゾーンの API v2.0（`/api/v2`、Classic 専用で、cron・github トリガーのみ）。Object Storage：公共ゾーンは `kr`／`krs.object.gov-ncloudstorage.com`（署名リージョン `gov-standard`／`gov2-standard`）、金融ゾーンは `kr.object.fin-ncloudstorage.com`（`fin-standard`）。NKS・NCR・SES・CDSS・Log Analytics：リージョンがパスに含まれ、（民間ゾーンは `sgn`／`jpn`、公共ゾーンは `krs`、金融ゾーンは `fkr`）サーバーが有効なリージョンを組み立てます。NKS 金融ゾーンのパス接頭辞は `/nks/v2`（他のゾーンは `/vnks/v2`）。Live Station 金融ゾーン：民間ゾーンのホストにパス接頭辞 `/api/fin-v2`。KMS 金融ゾーン：v1 ゲートウェイ（`kms.apigw.fin-ntruss.com`）の暗号化・復号 6 種のみ
ホストが規則（`*.apigw.gov-ntruss.com`）と異なる公共ゾーンサービス	Container Registry `gov-ncr`、Private CA `privateca`、VOD Station `vod-station`、KMS `ocapi.gov-ncloud.com`、Ncloud Storage/Object Storage/Archive `*.gov-ncloudstorage.com`
ホストが規則（`*.apigw.fin-ntruss.com`）と異なる金融ゾーンサービス	デフォルトゲートウェイ `fin-ncloud`、SES `fin-vpcsearchengine`、CDSS `fin-clouddatastreamingservice`、Billing `billingapi.apigw-pub`、SourceDeploy/SourcePipeline（`vpc` 接頭辞なし）、Live Station（民間ゾーンのホスト）、Object Storage `kr.object.fin-ncloudstorage.com`
移植していないサービス	民間・公共ゾーンの CDN+、Global CDN（民間は終了、公共は 2026-12-31 に終了予定 — Global Edge を使用）。金融ゾーンには Global Edge がないため、CDN+ 5 種を登録

該当ゾーンで提供されていないツールは登録されないため、ツール一覧に表示されません。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 が一度に参照するツール数が減るため、トークンコストを節約でき、ツール選択の精度も向上します。設定するには、mcp.json の env に NCLOUD_TOOL_GROUPS を 1 行追加します。（common は Region/Zone 共通のツールで、常に自動的に含まれます）

ひと目でわかる — どの値を使うか

希望すること	設定値	動作
（推奨）軽量な状態で始め、必要に応じて自動拡張	`dynamic`	コアセットで開始し、残りはセッション中に自動で有効化
特定のグループを毎日使用	`dynamic,analytics`	コアセット + analytics を開始時から ON にし、残りは拡張可能
最初からすべて有効にする	（未設定）または `all`	14 個のグループすべてを ON（従来の動作）
指定したグループだけを有効にし、実行時の拡張を禁止	`compute,network`	そのグループだけ — 実行時の拡張をロック
すべてから一部だけを除外	`all,-billing`	billing を除くすべて（`-` で除外したグループは enable もブロック）

重要なルール： セッション中にグループを拡張できるのは、dynamic キーワードがある場合のみです。dynamic を付けずにグループを列挙すると（例：compute,network）、「これだけ」を意味するロックになります。all／未設定の場合はすでにすべて有効であり、拡張する意味はありません（有効にできるグループが残っていません）。使用可能なグループキーの全一覧は、以下の詳細設定の表を参照してください。

권장: `dynamic` (동적 그룹)

전체를 다 켜는 대신 핵심 그룹만 켠 채 가볍게 시작하고, AI가 다른 서비스를 요청받으면 서버 재시작 없이 세션 중에 해당 그룹을 자동으로 켭니다.

{
  "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",
        "NCLOUD_TOOL_GROUPS": "dynamic"
      }
    }
  }
}

한 줄 요약: dynamic = "확장 모드 ON + 핵심 세트로 가볍게 시작". 안 쓰는 그룹은 처음에 안 올려 토큰을 아끼고, 필요할 때만 자동으로 켭니다.

시작 ON: common + compute + network + database (약 367개 도구 / 약 65k 토큰 — 전체 대비 63% 절감)
AI는 항상 켜져 있는 메타 도구로 나머지 그룹에 도달합니다:
- ncloud_list_tool_groups — 14개 그룹의 서비스·도구 수·현재 ON/OFF 조회
- ncloud_enable_tool_group — 그룹을 런타임에 활성화 (멱등)

dynamic vs all — 무엇이 다른가

	시작 시 로딩	안 쓰는 그룹	토큰(시작)
`all` / (미설정)	14개 그룹 전부	이미 다 켜져 있음	~177k
`dynamic`	핵심 세트만	필요할 때 자동으로 켜짐	~65k

둘 다 결국 모든 그룹을 쓸 수 있지만, dynamic은 "처음엔 핵심만, 나머지는 쓸 때" 방식이라 시작 컨텍스트가 가볍습니다. 이 절감이 dynamic의 존재 이유입니다.

동작 흐름 (예: Live Station 요청)

1. 서버 시작: 핵심 그룹 + 메타 도구만 ON
2. 사용자: "Live Station 채널 목록 보여줘"
3. AI: 카탈로그에서 media 그룹 확인 → ncloud_enable_tool_group("media")
4. 서버: media 도구 등록 + tools/list_changed 통지 → 클라이언트 도구 목록 갱신
5. AI: 새로 나타난 Live Station 도구 호출 → 작업 계속

켜진 상태는 세션 동안만 유지됩니다(다음 세션은 기본값으로 리셋).
dynamic에 그룹 키를 더하면 그 그룹은 "시작 즉시 ON"입니다(나중에 동적으로 붙는 게 아님). 예: dynamic,analytics는 핵심 세트 + analytics를 처음부터 켜고 나머지만 확장 대상으로 둡니다. 매일 쓰는 그룹은 이렇게 적어두면 enable 호출 없이 바로 씁니다.

클라이언트 호환성 — 동적 추가된 도구가 즉시 나타나려면 클라이언트가 tools/list_changed 통지를 지원해야 합니다.

클라이언트	`tools/list_changed`	비고
Claude Code	✅ 지원 (검증)	enable 즉시 같은 세션에서 새 도구 호출 가능
Claude Desktop	✅ 지원 (MCP 표준)	미검증
Kiro	❌ 미반영 (검증)	enable 해도 재시작 전까지 새 도구가 안 보임 — 아래 안내 참고
Cursor	⚠️ 미검증	도구 목록 변경에 수동 새로고침이 필요할 수 있음 — 자가 검증 권장
Codex	⚠️ 미검증	자가 검증 권장

💡 표에 없거나 "미검증"인 클라이언트는 30초만에 직접 확인할 수 있습니다. NCLOUD_TOOL_GROUPS=dynamic으로 설정 후 AI에게 *"media 그룹 켜고 Live Station 채널 목록 보여줘"*라고 요청 → 새 도구가 그 세션에서 호출되면 지원, AI가 도구를 못 찾으면 미지원이니 그룹을 미리 나열하는 방식으로 쓰면 됩니다.

list_changed 미지원 클라이언트(예: Kiro)에서는 dynamic의 세션 중 자동 확장이 동작하지 않습니다. enable은 되지만 새 도구가 도구 목록에 안 떠 호출할 수 없습니다. 이 경우 자주 쓰는 그룹을 미리 나열하세요 — 예: dynamic,governance,media처럼 시작부터 켜거나, 명시 리스트(compute,network,...)·all로 설정. (enable 응답도 같은 폴백을 안내합니다: NCLOUD_TOOL_GROUPS에 그룹을 추가하고 재시작.) 폴백 시 기존과 동일한 경험으로 회귀하므로 악화는 없습니다.

ℹ️ 권한 경계: MCP 도구가 노출된다고 권한이 부여되는 것은 아닙니다. Ncloud 측 실제 권한은 Access Key의 Sub Account 권한이 최종 경계입니다. 동적 로딩은 confirm 게이트·destructive 경고 등 기존 안전장치를 우회하지 않습니다.

詳細な制御 — 特定のグループのみを有効化／ロック

dynamic を指定せずにグループキーをカンマ区切りで列挙すると、そのグループのみが有効になり、実行時の拡張がロックされます（厳格な運用・最小権限の環境向け）。例："NCLOUD_TOOL_GROUPS": "compute,network,billing"。all,-billing のように - を付けて特定のグループを除外することもでき、除外されたグループは動的な有効化も拒否されます（運用者のセキュリティ境界）。

サーバー起動時に、どのグループが読み込まれたかをログで確認できます： ncloud-mcp-server: 4개 그룹 등록 (common, compute, network, billing) 無効なキーは無視され、警告のみが出力されます。

グループキー → 含まれるサービス

グループキー	含まれるサービス
`compute`	Server、Block Storage、Snapshot、Public IP、Login Key、Init Script、Placement Group、Fabric Cluster、Auto Scaling、Cloud Functions
`network`	VPC、Subnet、ACG、Network ACL、NAT Gateway、Route Table、VPC Peering、Network Interface、Load Balancer、Target Group、Global DNS、Global Traffic Manager
`database`	Cloud DB for MySQL / PostgreSQL / MSSQL / MongoDB / Cache（Redis/Valkey；公共ゾーンはユーザー（ACL）管理を含む） / Cloud DB Serverless（MySQL、民間ゾーン・メインアカウントキー専用）
`storage`	Object Storage、Ncloud Storage、NAS、Archive Storage
`containers`	Ncloud Kubernetes Service（NKS）、Container Registry
`monitoring`	Cloud Insight、Cloud Log Analytics
`governance`	Activity Tracer、Cloud Advisor（民間ゾーン）、Resource Manager、Sub Account、Web service Monitoring System、STS 呼び出し元の識別（`ncloud_get_caller_identity`）
`devtools`	SourceCommit、SourceBuild、SourceDeploy、SourcePipeline
`analytics`	Search Engine Service、Cloud Hadoop、Cloud Data Streaming Service、Data Stream/Catalog/Forest/Flow/Query（民間ゾーン）、Datafence・Cloud Data Box（民間ゾーン）
`media`	VOD Station、Live Station（民間ゾーン・金融ゾーン）、One Click Multi DRM
`cdn`	Global Edge（民間ゾーン・公共ゾーン）・CDN+（金融ゾーン専用 — 民間ゾーンは終了、公共ゾーンは2026-12-31に終了予定のため未登録）
`security`	Certificate Manager（公共ゾーンはプライベート証明書の発行を含む。民間ゾーンは2.0の `ncloud_cm2_*` を含む — メインアカウントキー専用）、Private CA、KMS、Security Monitoring、Secret Manager（民間ゾーン、`keyIsolation`）
`application`	API Gateway、SENS（SMS/通知トーク/ブランドメッセージ/Mail（民間ゾーン）、プロジェクト）、Cloud Outbound Mailer（民間ゾーンのレガシー／公共ゾーンの正式版）
`billing`	Billing（料金／価格の照会、コスト・使用量、割引）
`common` (常に ON)	リージョン／ゾーン共通

使用例

MCP クライアントから自然言語で Ncloud インフラストラクチャを管理できます：

"현재 서버 목록을 보여줘"
"KR-2 존에 Ubuntu 서버를 하나 만들어줘"
"my-vpc의 서브넷 목록을 조회해줘"
"Cloud DB for MySQL 인스턴스 상태를 확인해줘"
"Object Storage에 새 버킷을 만들어줘"
"로드밸런서에 연결된 타겟 그룹을 확인해줘"
"Cloud Insight에서 CPU 사용률 상위 서버를 조회해줘"

対応リージョン

民間ゾーン（NCLOUD_ZONE=pub、デフォルト）

リージョン	コード
韓国	`KR`
日本	`JPN`
シンガポール	`SGN`

参考： 米国西部（USWN）、ドイツ（DEN）リージョンは Classic 環境のみ対応しているため、VPC ベースの本 MCP サーバーでは使用が制限されます。

公共ゾーン（NCLOUD_ZONE=gov）

リージョン	コード
韓国首都圏（KR-CENTRAL）	`KR`
韓国南部圏（KR-SOUTH）	`KRS`

参考： 公共ゾーンの Ncloud Storage・Archive Storage は KR の単一リージョンです。Object Storage は KR（gov-standard）・KRS（gov2-standard）の2つのリージョンに対応しています。ncloud_set_region で指定できるのは、ゾーンのリージョン一覧に含まれるリージョンのみです。

金融ゾーン（NCLOUD_ZONE=fin）

リージョン	コード
韓国（金融）	`FKR`

参考： 金融ゾーンは FKR の単一リージョンです。NCLOUD_REGION が未設定の場合、FKR がデフォルトになります。Object Storage は kr.object.fin-ncloudstorage.com（署名リージョン fin-standard）を使用します。

トラブルシューティング

症状	原因	解決方法
サーバー起動時にすぐ終了する	環境変数が未設定	`NCLOUD_ACCESS_KEY`、`NCLOUD_SECRET_KEY` の環境変数が設定されていることを確認してください
`認証失敗`（HTTP 401）	API 認証キーのエラー	ポータルでキーの状態が有効になっていることを確認してください。キーの値に空白や改行が含まれていないことを確認してください
`アクセス拒否`（HTTP 403）	サービス権限の不足	サービス利用を申請済みか確認してください。Sub Account を使用する場合は、該当サービスの API 権限を付与する必要があります
`無効なリージョンです`	リージョンコードが無効	対応リージョン（KR、JPN、SGN）を確認してください。`ncloud_set_region` ツールで変更できます
`サービスを一時的に利用できません`（HTTP 503）	API エンドポイントに接続できない	ネットワークの状態を確認してください。ファイアウォール／プロキシ環境では、`ncloud.apigw.ntruss.com` へのアウトバウンド通信を許可する必要があります
`リクエストがタイムアウトしました`（HTTP 504）	API の応答遅延	しばらくしてから再試行してください。継続する場合は Ncloud のステータスページを確認してください
`リクエスト制限を超過しました`（HTTP 429）	API のレート制限に到達	リクエストの間隔を空けて再試行してください

プロジェクト構成

ncloud-mcp-server/
├── src/
│   ├── index.ts              # MCP 서버 엔트리포인트 (stdio transport)
│   ├── auth/
│   │   └── signature.ts      # HMAC-SHA256 서명 생성
│   ├── client/
│   │   ├── ncloud-client.ts  # Ncloud API HTTP 클라이언트
│   │   ├── s3-compatible-client.ts   # Object Storage (S3 호환)
│   │   └── swift-compatible-client.ts # Archive Storage (Swift 호환)
│   └── tools/                # 서비스별 MCP 도구 (63개 파일)
│       ├── compute-server.ts
│       ├── vpc.ts
│       ├── cloud-insight.ts
│       └── ...
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md

開発

# 빌드
npm run build

# 테스트
npm test

# 타입 체크
npx tsc --noEmit

貢献

イシューと PR を歓迎します。貢献する際は、以下を参考にしてください：

Fork して feature ブランチで作業
npm run build でビルドを確認
npm test でテストに合格することを確認
PR を提出

ライセンス

MIT

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

Ncloud MCP Server

Ncloud MCP Server について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

Ncloud MCP サーバー

主な機能

前提条件

注意事項

インストール

npx（推奨 — インストール不要）

ソースからビルド

環境変数

ゾーンの選択（民間ゾーン／公共ゾーン／金融ゾーン）

MCP クライアントの設定

npx を使用（推奨）

ソースからビルドして使用

ツールグループの選択（任意）

ひと目でわかる — どの値を使うか

권장: dynamic (동적 그룹)

詳細な制御 — 特定のグループのみを有効化／ロック

使用例

対応リージョン

トラブルシューティング

プロジェクト構成

開発

貢献

ライセンス

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？

권장: `dynamic` (동적 그룹)