ncloud-mcp

한국어 안내 · Security and operations · Architecture

A small, service-modular NAVER Cloud MCP server. The first implemented service is CLOVA Speech long-form transcription. Object Storage management, account/identity, and billing/usage are planned modules, not available tools. No generic cloud API passthrough is provided.

This uses the official NAVER Cloud CLOVA Speech API, not CLOVA Note browser endpoints. A CLOVA Note/web subscription does not supply the Invoke URL and secret needed here; do not assume it includes API usage. Obtain a separate Speech domain and review its billing. This server requires no broad NAVER Cloud account access key. It is an independent community project, not an official NAVER product.

Install locally

Requires Python 3.12+ and a trusted stdio MCP host. Linux/macOS support bounded local file access; on other systems use URL/Object Storage inputs (local files fail closed). No package has been published to PyPI. From this source checkout:

python3.12 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/ncloud-mcp --check

For development with uv:

uv sync --frozen
uv run ncloud-mcp --check
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest
uv build

Copy .env.example to a private location for reference and configure your host's environment securely. The server intentionally does not load .env files automatically. Never commit real values or paste keys into chat. NCLOUD_SPEECH_ENABLED=true exposes Speech tools; the default is disabled. An enabled module without its own credentials remains unconfigured and rejects API calls. --check and ncloud_health make no network requests and return only flags and limits.

Example MCP host configuration (replace the executable path; inherit private environment variables from the host):

{
  "mcpServers": {
    "ncloud": {
      "command": "/absolute/path/ncloud-mcp/.venv/bin/ncloud-mcp",
      "args": []
    }
  }
}

Prepare an Object Storage bucket before creating the CLOVA Speech domain, as required by the domain setup guide. This domain prerequisite applies even when using synchronous local-file or URL input. Those input methods do not require pre-uploading the recording into the bucket or providing Object Storage credentials to this MCP.

Set NCLOUD_SPEECH_INVOKE_URL to the domain's base Invoke URL (without /recognizer/...) and NCLOUD_SPEECH_SECRET to its secret. Supported base URLs are deliberately restricted to the official https://clovaspeech-gw.ncloud.com/external/v1/<domain-id>/<invoke-key> format; custom proxies are unsupported. For files, explicitly set NCLOUD_SPEECH_LOCAL_ROOTS to dedicated recording directories, separated with the OS path separator. Do not allow your home, repository, or credentials directory.

Related MCP server: io.github.chicogong/ffvoice

Tools

Pass this argument to clova_speech_transcribe:

{"request":{"source":"file","location":"/dedicated/audio/sample.wav","language":"ko-KR","diarization":true,"completion":"sync","result_to_obs":false}}

Sources: file (absolute allowed path), url (trusted, allowlisted public HTTPS origin), or object_storage (dataKey within the Speech domain's recognition target storage). Enable the latter explicitly with NCLOUD_SPEECH_ALLOW_OBJECT_STORAGE=true. URL recognition does not download media through this process; NAVER fetches it. Allow only origins you control/trust, including their redirects; DNS checks cannot guarantee the provider's later fetch destination. Private IPs, credentials in URLs, fragments, and nonstandard ports are rejected. URL/Object Storage media size and duration cannot be inspected locally; the provider validates those inputs.

Languages: ko-KR, en-US, enko, ja, zh-cn, zh-tw; availability can depend on domain. Supported file extensions follow the official long-form API. Default local upload cap: 25 MiB, configurable up to 250 MiB, deliberately below the provider limit. Recognition duration is not inferred from file extensions or bytes. See verified API behavior for provider limits and references.

File/URL sync requires no input pre-upload or MCP Object Storage credentials, while the domain's bucket prerequisite still applies. Async in this release uses only resultToObs=true, which persists the transcript in the Speech domain's configured Object Storage. It requires NCLOUD_SPEECH_ALLOW_ASYNC_OBS=true, completion="async", and result_to_obs=true. Configure the domain's result storage and permissions yourself before use. Arbitrary callbacks are intentionally unsupported. Acceptance (SUCCEEDED) is not a completed transcript; retain the returned token privately and call clova_speech_job_status with {"token":"<returned-token>"}. Missing or invalid async tracking tokens produce a sanitized unknown/untrackable-outcome error: NAVER may already have accepted a billable job, so do not automatically resubmit. There is no automatic polling, cancellation, or invented poll-only submission mode.

Results contain status, optional job token, text, and segments with start_ms, end_ms, text, optional speaker label/confidence, and word timing. Job results without full text reconstruct it from segments. Upstream messages, domain metadata, and raw responses are omitted. A FAILED/TIMEOUT job is returned as a terminal status; upstream error codes produce sanitized tool errors. Transcript text is untrusted data, never instructions to execute.

See the Python MCP client example for programmatic usage.

Connection and packaging

The server is stdio only. It has no HTTP listener or public endpoint. Do not expose it via an unauthenticated HTTP bridge. The portable local plugin manifest and MCP configuration require ncloud-mcp installed on the host PATH and environment configured privately; they are source templates, not an installed or verified ChatGPT connector. The protocol integration test launches the real server subprocess and calls the harmless health tool.

MIT licensed. No recordings, real credentials, or private integrations are included. No live transcription, storage, account, or billing calls are used in tests.