Skip to main content
Glama
README.md
# ncloud-mcp-server

[한국어](https://github.com/revert12/ncloud-mcp-server/blob/main/README.ko.md) | **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`** |

```jsonc
// 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_read` accepts only read actions such as
  `get*`, `list*` and `describe*`, 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 as `terminateserverinstances`, `TerminateServerInstances` or
  `terminateServerInstances/x`, is treated as a write and blocked.
- **Read actions that return secrets** (`getRootPassword`, `getRootPasswordServerInstanceList`, the NKS
  `kubeconfig`) are blocked in `ncp_read`. If you really need one, add it to
  `NCP_WRITE_ALLOWLIST` and call it with `ncp_write`.
- Writes are possible only through `ncp_write`, which appears only when the server runs with
  `NCP_ALLOW_WRITE=true`. Each action must also be listed in `NCP_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-accounts` for POST with 0.5.x or earlier, add the method.
- 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 and `truncated` explains why. With several calls, `ncp_read` splits this
  budget across them. If a result was cut, use `fields` to 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 **allowing `ncp_read`, and asking every time for `ncp_write`**.
  (Claude Code example: `mcp__ncloud__ncp_read` in `permissions.allow`, `mcp__ncloud__ncp_write` in `permissions.ask`)
- Signed requests are sent only to the selected zone's API gateway domains (`*.apigw.ntruss.com` etc.).
- 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](https://docs.astral.sh/uv/).

**Claude Code**: register it with one command.

```sh
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 project
- `project`: stored in `.mcp.json` at 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.

```jsonc
// .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.

```ini
[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`, `gov` or `fin`) 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_KEY` and `NCLOUD_ZONE` adds an `env-<zone>` profile.
- `NCP_MCP_CONFIG` changes 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

```sh
uv sync
uv run pytest
```

See [CONTRIBUTING.md](https://github.com/revert12/ncloud-mcp-server/blob/main/CONTRIBUTING.md) for setup, the pre-commit secret scan, and how the read-only guard is verified.

## License

MIT

TDQS

A3.9/5.0

Scored across 3 tools

Disambiguation4/5

Each tool targets a distinct layer: ncp_profiles for credential/config inspection, ncp_call for a single API request, and ncp_batch for concurrent multi-request execution. The only mild overlap is that ncp_batch is effectively a fan-out wrapper over ncp_call, but the descriptions make the boundary clear (order-preserving, per-item failure isolation, per-item profile override).

Naming Consistency4/5

All names share a consistent ncp_ prefix and snake_case form, which reads well as a family. The only minor deviation is that ncp_profiles is a noun while ncp_call and ncp_batch are verbs, but the intent of each is still immediately clear.

Tool Count4/5

Three tools is lean but appropriate for a generic gateway design, where the breadth lives inside ncp_call's service/action arguments rather than in separate tools. Nothing feels redundant or missing at the tool level, though the surface is on the thin side.

Completeness3/5

The read-only call/batch pair covers querying well, including pagination, field filtering, and credential selection. However, there is no discovery/introspection tool to enumerate available services and actions (or their schemas), so an agent must already know Ncloud API paths, and no write operations are exposed despite the mention of a writes-enabled flag.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues