ncloud-mcp-server
한국어 | English
A lightweight MCP server for NAVER Cloud Platform (Ncloud).
Instead of one tool per API, a few signed, generic call tools reach every Ncloud API. The tool definitions are small, so connecting the server costs almost no conversation context.
This is not an official NAVER Cloud project.
Tools
| Tool | Description |
|---|---|
ncp_profiles |
Usable profiles and zones, profiles disabled by the rules (with the reason), and whether writes are enabled. With verify=true, shows who owns each key (account ID, login alias, main/sub account). Secrets are never returned |
ncp_read |
1 to 50 read-only API calls, run 5 at a time. Handles signing, responseFormatType=json, list parameter expansion, automatic paging, and fields to return only the fields you need. A failed item does not affect the others |
ncp_write |
Calls APIs that create, change or delete resources. Registered only when the server runs with NCP_ALLOW_WRITE=true |
// Server list (only the fields you need)
ncp_read(calls=[{"service": "vserver", "action": "getServerInstanceList", "params": {"regionCode": "KR"},
"fields": ["serverName", "serverInstanceStatus.code", "privateIp"]}])
// Sub accounts (REST-style service)
ncp_read(calls=[{"service": "subaccount", "action": "/sub-accounts"}])
// Several regions at once
ncp_read(calls=[
{"service": "vserver", "action": "getServerInstanceList", "params": {"regionCode": "KR"}},
{"service": "vserver", "action": "getServerInstanceList", "params": {"regionCode": "JPN"}}
])
Safety
- Reads and writes are separate tools.
ncp_readaccepts only read actions such asget*,list*anddescribe*, plus REST-style GETs. Ncloud's shared API gateway accepts even delete actions over GET, so operations are classified by action name, not by HTTP method. - Only actions proven read-only are allowed. On shared-gateway services an action counts as a read
only if it is a single path segment in camelCase starting with a read verb (
getServerInstanceList). Anything else, such asterminateserverinstances,TerminateServerInstancesorterminateServerInstances/x, is treated as a write and blocked. - Read actions that return secrets (
getRootPassword,getRootPasswordServerInstanceList, the NKSkubeconfig) are blocked inncp_read. If you really need one, add it toNCP_WRITE_ALLOWLISTand call it withncp_write. - Writes are possible only through
ncp_write, which appears only when the server runs withNCP_ALLOW_WRITE=true. Each action must also be listed inNCP_WRITE_ALLOWLIST(comma separated). Write requests are never retried.- For shared-gateway services, write
vserver:stopServerInstances. The shared gateway takes GET and POST as the same call, so both are allowed. - For REST-style services, put the method first:
POST subaccount:/sub-accounts,DELETE subaccount:/sub-accounts/123. An entry without a method allows GET only, and allowing POST on a path does not allow DELETE on it. - If you used an entry like
subaccount:/sub-accountsfor POST with 0.5.x or earlier, add the method.
- For shared-gateway services, write
- Callable services are limited to a per-zone allowlist (
src/ncp_mcp/endpoints.py, based on the official NCP API docs). To use a service that is not listed, add it explicitly, e.g.NCP_MCP_EXTRA_SERVICES="gov:cdn". - Read requests are retried up to 2 times on 429, 5xx and timeouts (
NCP_MCP_RETRIES), and concurrent requests are limited to 5 (NCP_MCP_CONCURRENCY). - A single result is capped at 100,000 characters of JSON, about 25,000 tokens (
NCP_MCP_MAX_RESULT_CHARS). Beyond that, only the first list items are kept andtruncatedexplains why. With several calls,ncp_readsplits this budget across them. If a result was cut, usefieldsto keep only the columns you need, or narrow the query. - Every tool carries the standard MCP hints (
readOnlyHint/destructiveHint). In your client's permission settings we recommend allowingncp_read, and asking every time forncp_write. (Claude Code example:mcp__ncloud__ncp_readinpermissions.allow,mcp__ncloud__ncp_writeinpermissions.ask) - Signed requests are sent only to the selected zone's API gateway domains (
*.apigw.ntruss.cometc.). - Keys never appear in error messages or results. The final permission boundary is the sub-account permissions of the access key, so we recommend a sub-account key with read-only permissions.
Installation
Requires Python 3.10+ and uv.
Claude Code: register it with one command.
claude mcp add ncloud --scope user -- uvx --from git+https://github.com/revert12/ncloud-mcp-server@v0.7.0 ncloud-mcp-server
--scope picks where it is registered.
local(default): only you, only in the current project (stored in~/.claude.json)user: only you, in every projectproject: stored in.mcp.jsonat the project root and shared with your team
Check with claude mcp list; remove with claude mcp remove ncloud.
Other MCP clients: add it to the config file directly.
// .mcp.json
{
"mcpServers": {
"ncloud": {
"command": "uvx",
"args": ["--from", "git+https://github.com/revert12/ncloud-mcp-server@v0.7.0", "ncloud-mcp-server"]
}
}
}
Pinning a version with a tag is recommended.
Credentials
The server reads ~/.ncloud/configure (INI), the same file the Ncloud CLI uses. Each section is one profile.
[mycompany-pub]
ncloud_access_key_id = <access key>
ncloud_secret_access_key = <secret key>
ncloud_zone = pub
[customer-a-gov]
ncloud_access_key_id = <gov access key>
ncloud_secret_access_key = <gov secret key>
ncloud_zone = gov
Profile rules (a profile that breaks one is not used; ncp_profiles lists it under disabled with the reason)
ncloud_zone(pub,govorfin) is required.- Profile names use lowercase letters, digits and hyphens, and must end with the zone (
-pub,-gov,-fin), so the zone is visible from the name alone. For the same reason[DEFAULT]cannot be used. - With two or more profiles, every call must name its
profile. There is no default profile. - Usable profile names are written into the tool definitions as choices when the server starts. Restart the MCP server after changing profiles.
ncp_profiles(verify=true)asks STS (caller-identity) which NCP account and user each key really belongs to.
The Ncloud CLI can use the same profiles with --profile <name>.
- Setting the environment variables
NCLOUD_ACCESS_KEY,NCLOUD_SECRET_KEYandNCLOUD_ZONEadds anenv-<zone>profile. NCP_MCP_CONFIGchanges the location of the config file.
Service endpoints
| Service | Endpoint |
|---|---|
| Default (shared gateway) | https://ncloud.apigw.<zone>/<service>/v2/<action> |
billing |
https://billingapi.apigw.<zone>/billing/v1 |
subaccount |
https://subaccount.apigw.<zone>/api/v1 |
sts |
https://sts.apigw.<zone>/api/v1 |
vnks, vses, vcdss, source*, etc. |
See SPECIAL in src/ncp_mcp/endpoints.py |
<zone> is ntruss.com (public), gov-ntruss.com (government) or fin-ntruss.com (financial).
Development
uv sync
uv run pytest
See CONTRIBUTING.md for setup, the pre-commit secret scan, and how the read-only guard is verified.
License
MIT
Metadata
Release files for ncloud-mcp-server 0.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ncloud_mcp_server-0.7.0.tar.gz | 115.9 kB | With provenance | Details for ncloud_mcp_server-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ncloud_mcp_server-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for ncloud_mcp_server-0.7.0-py3-none-any.whl |
Total release size: 139.1 kB
Release files / ncloud_mcp_server-0.7.0.tar.gz
| Download URL | ncloud_mcp_server-0.7.0.tar.gz |
|---|---|
| Size | 115.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
64d0d537a881ccde262ea8283a064c2f4b9758037f180ffe631609395e1eff91
|
|
BLAKE2b-256 checksum How to use checksums |
877959d10c9154344d1e72da2ad27c06db7b4426f9dcd8006741af145a81fd06
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / ncloud_mcp_server-0.7.0-py3-none-any.whl
| Download URL | ncloud_mcp_server-0.7.0-py3-none-any.whl |
|---|---|
| Size | 23.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9c886cb47e2cd8d943ff71fc461e95ab8b58c9808f28df74a5278f9cd4d69158
|
|
BLAKE2b-256 checksum How to use checksums |
55df0e909097bb8400ebbb6735786d2a3555bd4c25821aacce5f7e944d416800
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for ncloud-mcp-server 0.7.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ncloud_mcp_server-0.7.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.