cloud-mcp

A Node.js skeleton for wrapping multiple cloud CLIs behind one command surface.

What this gives you

• Unified CLI entrypoint (cloud-wrap)

• Provider pass-through commands for AWS, GCP, Azure, OCI, Alibaba, DigitalOcean, IBM Cloud, Tencent Cloud, and Huawei Cloud

• Config file support to override command paths and inject environment variables

• Vault abstraction for storing provider attributes with optional external replacement

• MCP stdio server that registers provider tools and command runners

• Structured logging and safe command execution with inherited stdio

Related MCP server: mcp_server_for_claudes_toolbox

Quick start

npm install
npm run bootstrap:clis
npm start -- list
npm start -- aws sts get-caller-identity
npm start -- oci iam region list
npm start -- alibaba ecs DescribeInstances
npm run mcp

Repository-local CLI layout

This project can keep provider CLI entrypoints under mcp/<provider>/bin.

• mcp/aws/bin/aws

• mcp/gcp/bin/gcloud

• mcp/azure/bin/az

• mcp/oci/bin/oci

• mcp/alibaba/bin/aliyun

• mcp/digitalocean/bin/doctl

• mcp/ibmcloud/bin/ibmcloud

• mcp/tencent/bin/tccli

• mcp/huawei/bin/hcloud

Run the bootstrap command to create links from your installed CLIs into this structure:

npm run bootstrap:clis

Or pull and install all CLIs directly into the structure:

npm run install:clis

This installer covers AWS, GCP, Azure, OCI, Alibaba, DigitalOcean, IBM Cloud, and Tencent Cloud directly. Huawei Cloud is wired through the same provider interface, but the public huaweicloudcli Python package referenced by older installer versions is not available; set HUAWEI_CLI_BIN to a supported hcloud-compatible binary to enable Huawei command execution.

At runtime, provider resolution order is:

1. mcp/<provider>/bin/<cli> when present

2. <PROVIDER>_CLI_BIN environment override

3. CLI from PATH

If neither HUAWEI_CLI_BIN nor hcloud on PATH is available during npm run install:clis, a placeholder mcp/huawei/bin/hcloud is created that fails with an explicit setup message instead of breaking the image build.

Shared command limits live in mcp/cloud-command-limits.json.

Current repository default (mcp/cloud-command-limits.json) is permissive for all providers and intentionally includes CLI-style aliases for two sections:

{
  "alibaba.*": [],
  "aws.*": [],
  "az.*": [],
  "digitalocean.*": [],
  "gcloud.*": [],
  "huawei.*": [],
  "ibmcloud.*": [],
  "oci.*": [],
  "tencent.*": []
}

At load time this is normalized to canonical provider sections, so az.* becomes azure.* and gcloud.* becomes gcp.* in the effective runtime policy.

External command-limit loading:

• CLOUD_COMMAND_LIMITS_SOURCE (optional): load command limits from an external source at startup.

  • Supported values: file path, file:// URL, http:// URL, https:// URL.

• CLOUD_COMMAND_LIMITS_REFRESH_INTERVAL_SECONDS (optional): when CLOUD_COMMAND_LIMITS_SOURCE is set and this value is > 0, command limits are reloaded on that interval.

• If refresh fails, the last successfully loaded limits remain active.

PostgreSQL-backed command limits:

• Command limits are persisted in PostgreSQL table cloud_mcp.command_limits.

• Runtime command validation reads limits from the database before each provider command execution.

• On startup, limits are loaded from mcp/cloud-command-limits.json (or CLOUD_COMMAND_LIMITS_SOURCE) and synced into PostgreSQL.

• When refresh is enabled, each refresh cycle updates PostgreSQL records from the external source.

Database environment variables:

• COMMAND_LIMITS_DATABASE_URL (preferred), or

• DATABASE_URL

• COMMAND_LIMITS_LOCAL_POSTGRES_ENABLED (optional): when true|1|yes and no external DB URL is set, auto-uses local postgres URL.

• COMMAND_LIMITS_LOCAL_POSTGRES_PORT (required when local postgres auto-mode is enabled): local postgres port used to build the DB URL.

If neither database variable is set, command limits run in in-memory mode.

Database resolution order:

1. Use COMMAND_LIMITS_DATABASE_URL when set.

2. Else use DATABASE_URL when set.

3. Else if COMMAND_LIMITS_LOCAL_POSTGRES_ENABLED=true|1|yes, require COMMAND_LIMITS_LOCAL_POSTGRES_PORT and use postgres://cloud_mcp:cloud_mcp@127.0.0.1:<port>/cloud_mcp.

4. Else run in-memory mode.

Start local PostgreSQL from repository assets:

export COMMAND_LIMITS_LOCAL_POSTGRES_PORT=5432
docker compose -f docker-compose.postgres.yml up -d
export COMMAND_LIMITS_DATABASE_URL="postgres://cloud_mcp:cloud_mcp@127.0.0.1:5432/cloud_mcp"

Standalone migration for existing databases:

psql "$COMMAND_LIMITS_DATABASE_URL" -f db/migrations/002_command_limits_namespace_migration.sql

This migration creates cloud_mcp.command_limits, copies legacy rows from public.command_limits when present, and ensures default provider-prefix records exist.

• Enforced sections are keyed by provider prefix: aws.*, gcp.*, azure.*, oci.*, alibaba.*, digitalocean.*, ibmcloud.*, tencent.*, huawei.*

• If a section is an empty array, all commands for that provider are allowed

• If a section contains entries, only matching prefixes are allowed

• Entries may be written as full prefixes like aws.s3 or shorthand like s3 within the aws.* section

Prefix naming note:

• Runtime enforcement uses provider names (aws, gcp, azure, oci, alibaba, digitalocean, ibmcloud, tencent, huawei), not binary names.

• CLI-style aliases are supported and normalized during load:

  • gcloud.* maps to gcp.*

  • az.* maps to azure.*

  • aliyun.* maps to alibaba.*

  • doctl.* maps to digitalocean.*

  • tccli.* maps to tencent.*

  • hcloud.* maps to huawei.*

• If both canonical and alias keys are provided for the same provider, canonical keys win (gcp.* over gcloud.*, azure.* over az.*, alibaba.* over aliyun.*, digitalocean.* over doctl.*, tencent.* over tccli.*, huawei.* over hcloud.*).

• Recommended mapping is:

  • aws.* for aws

  • gcp.* for gcloud

  • azure.* for az

  • oci.* for oci

  • alibaba.* for aliyun

  • digitalocean.* for doctl

  • ibmcloud.* for ibmcloud

  • tencent.* for tccli

  • huawei.* for hcloud

How to fill out the file:

1. Allow everything for every cloud:

{
  "alibaba.*": [],
  "aws.*": [],
  "digitalocean.*": [],
  "gcp.*": [],
  "azure.*": [],
  "oci.*": [],
  "ibmcloud.*": [],
  "tencent.*": [],
  "huawei.*": []
}

2. Restrict AWS and GCP, leave Azure and OCI open:

{
  "alibaba.*": ["ecs"],
  "aws.*": ["s3", "sts.get-caller-identity"],
  "gcp.*": ["projects", "compute.instances.list"],
  "azure.*": [],
  "oci.*": [],
  "digitalocean.*": ["compute"],
  "ibmcloud.*": [],
  "tencent.*": ["cvm"],
  "huawei.*": ["ecs"]
}

3. Use full provider-prefixed entries explicitly:

{
  "aws.*": ["aws.s3", "aws.sts.get-caller-identity"],
  "gcp.*": ["projects", "compute.instances.list"],
  "azure.*": [],
  "oci.*": ["oci.iam"]
}

4. Lock each provider to a narrow subset:

{
  "aws.*": ["ec2.describe-instances", "s3.ls"],
  "gcp.*": ["projects.list"],
  "azure.*": ["vm", "account.show"],
  "oci.*": ["iam.region.list"]
}

What the entries mean:

• "s3" inside aws.* means any AWS command starting with aws.s3...

• "sts.get-caller-identity" inside aws.* means only aws sts get-caller-identity

• "projects" inside gcp.* means any GCP command starting with gcp.projects...

• "oci.iam" inside oci.* means any OCI command starting with oci.iam...

With this file:

• aws s3 ls is allowed

• aws ec2 describe-instances is denied

• all Azure commands are allowed

• gcloud projects list is allowed

• oci iam region list is allowed

Usage

Generic form

npm start -- run <provider> [args...]

Examples:

npm start -- run aws s3 ls
npm start -- run gcp projects list
npm start -- run azure account show
npm start -- run oci iam region list
npm start -- run digitalocean compute droplet list

Provider shorthands

npm start -- aws s3 ls
npm start -- gcp projects list
npm start -- azure account show
npm start -- oci iam region list
npm start -- tencent cvm DescribeInstances

MCP server

Start MCP with both stdio and HTTP transports (default):

npm run mcp -- --config cloud-wrap.config.json

Run HTTP-only or stdio-only:

npm run mcp:http -- --config cloud-wrap.config.json
npm run mcp -- --transport stdio --config cloud-wrap.config.json

HTTP defaults:

• MCP_HTTP_HOST=127.0.0.1

• MCP_HTTP_PORT=3000

• MCP_HTTP_PATH=/mcp

• MCP_HTTP_HEALTH_PATH=/healthz

Transport mode:

• MCP_TRANSPORT_MODE=stdio|http|both (default: both)

HTTP authentication framework:

• MCP_HTTP_AUTH_MODE=none|token|oauth2|both (default: none)

• Bearer token mode (token or both):

  • MCP_HTTP_TOKEN_SOURCE=env|vault (default: env)

  • MCP_HTTP_AUTH_TOKENS (comma-separated bearer tokens)

  • Vault source settings (when MCP_HTTP_TOKEN_SOURCE=vault):

    • MCP_HTTP_VAULT_TOKEN_INDEX_PATH (default: cloud-mcp/http/auth/token-index)

    • MCP_HTTP_VAULT_TOKEN_DEFAULT_USER_ID (default: default)

    • MCP_HTTP_VAULT_TOKEN_REQUIRED_SCOPES (comma-separated, optional)

    • MCP_HTTP_VAULT_TOKEN_REQUIRED_AUDIENCE (comma-separated, optional)

    • MCP_HTTP_VAULT_TOKEN_CACHE_TTL_MS (optional)

• OAuth2 introspection mode (oauth2 or both):

  • MCP_HTTP_OAUTH2_INTROSPECTION_URL

  • MCP_HTTP_OAUTH2_CLIENT_ID (optional)

  • MCP_HTTP_OAUTH2_CLIENT_SECRET (optional)

  • MCP_HTTP_OAUTH2_REQUIRED_SCOPES (comma-separated, optional)

  • MCP_HTTP_OAUTH2_REQUIRED_AUDIENCE (comma-separated, optional)

  • MCP_HTTP_OAUTH2_TIMEOUT_MS (optional)

  • MCP_HTTP_OAUTH2_CACHE_TTL_MS (optional)

HTTP hardening controls:

• MCP_HTTP_TRUST_PROXY (optional: true|false)

• MCP_HTTP_ALLOWED_ORIGINS (comma-separated allowlist)

• MCP_HTTP_ALLOWED_IPS (comma-separated allowlist)

• MCP_HTTP_RATE_LIMIT_WINDOW_MS (default: 60000)

• MCP_HTTP_RATE_LIMIT_MAX_REQUESTS (default: 60)

• MCP_HTTP_MAX_BODY_BYTES (default: 1048576)

When allowlists are set:

• requests outside allowed IPs are rejected with 403

• requests with disallowed origin/host are rejected with 403

• per-IP rate limit violations return 429 with Retry-After

Example: bearer tokens only

export MCP_HTTP_AUTH_MODE=token
export MCP_HTTP_AUTH_TOKENS="dev-token-1,dev-token-2"
npm run mcp -- --config cloud-wrap.config.json

Example: Vault-backed bearer token index

export MCP_HTTP_AUTH_MODE=token
export MCP_HTTP_TOKEN_SOURCE=vault
export MCP_HTTP_VAULT_TOKEN_INDEX_PATH="cloud-mcp/http/auth/token-index"
npm run mcp -- --config cloud-wrap.config.json

Vault token index shape (tokens stored by SHA-256 hash, not plaintext):

{
  "tokens": {
    "<sha256(token)>": {
      "userId": "default",
      "tokenId": "tok-123",
      "active": true,
      "scopes": ["mcp:invoke"],
      "audience": ["cloud-mcp"],
      "expiresAt": "2026-12-31T23:59:59Z"
    }
  }
}

Example: OAuth2 introspection only

export MCP_HTTP_AUTH_MODE=oauth2
export MCP_HTTP_OAUTH2_INTROSPECTION_URL="https://auth.example.com/oauth2/introspect"
export MCP_HTTP_OAUTH2_CLIENT_ID="cloud-mcp"
export MCP_HTTP_OAUTH2_CLIENT_SECRET="replace-me"
export MCP_HTTP_OAUTH2_REQUIRED_SCOPES="mcp:invoke"
npm run mcp -- --config cloud-wrap.config.json

Register This MCP In Codex, VS Code, and Claude

Use stdio transport for client registration. Keep this repository path and config path as absolute paths.

1. Start from a known absolute repo path:

cd /Users/lesterjohn/Documents/GitHub/cloud-mcp
pwd

2. Confirm local launch command works before registering:

npm run mcp -- --transport stdio --config /Users/lesterjohn/Documents/GitHub/cloud-mcp/cloud-wrap.config.json

3. Register in Codex. On macOS, edit ~/.codex/config.toml and add:

[mcp_servers.cloud-mcp]
command = "npm"
args = [
  "run",
  "mcp",
  "--",
  "--transport",
  "stdio",
  "--config",
  "/Users/lesterjohn/Documents/GitHub/cloud-mcp/cloud-wrap.config.json"
]
cwd = "/Users/lesterjohn/Documents/GitHub/cloud-mcp"

4. Register in VS Code. Create or update workspace file .vscode/mcp.json with:

{
  "servers": {
    "cloud-mcp": {
      "command": "npm",
      "args": [
        "run",
        "mcp",
        "--",
        "--transport",
        "stdio",
        "--config",
        "/Users/lesterjohn/Documents/GitHub/cloud-mcp/cloud-wrap.config.json"
      ],
      "cwd": "/Users/lesterjohn/Documents/GitHub/cloud-mcp"
    }
  }
}

Then reload VS Code window and verify cloud-mcp appears in MCP server list.

5. Register in Claude Desktop. On macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json and add:

{
  "mcpServers": {
    "cloud-mcp": {
      "command": "npm",
      "args": [
        "run",
        "mcp",
        "--",
        "--transport",
        "stdio",
        "--config",
        "/Users/lesterjohn/Documents/GitHub/cloud-mcp/cloud-wrap.config.json"
      ],
      "cwd": "/Users/lesterjohn/Documents/GitHub/cloud-mcp"
    }
  }
}

6. Restart the client app after config changes.

7. Validate tool registration from the client by calling discover_tools first, then list_providers or run_provider based on the returned recommendation.

Notes:

• If your client already has config content, merge only the cloud-mcp server entry.

• If your environment needs auth, set env vars before launching the client (MCP_HTTP_*, MCP_PROVIDER_AUTH_KEY, Vault vars).

• For remote HTTP integration instead of stdio, run npm run mcp:http and register endpoint http://127.0.0.1:3000/mcp with the client that supports streamable HTTP MCP.

MCP Tool Reference

The MCP server exposes the following tools. Read-only tools are safe to inspect state; mutating tools change vault, database, or token-index data and should be used carefully.

• discover_tools is read-only. Use it first when you need schema discovery, want a recommendation for which MCP tool fits a task, or need the input schema for a specific tool before calling it.

• list_providers is read-only. Use it to discover which provider names are currently available before calling get_provider or run_provider.

• get_provider is read-only. It returns the stored provider configuration or null if missing. If MCP_PROVIDER_AUTH_KEY is set, authorizationKey is required.

• set_provider mutates vault state and is high-risk because it changes what future CLI calls execute. Use it to register or replace a provider config. The required payload is config.command; env defaults to {}; profiles.*.users is optional and an empty list means any user may use the profile.

• run_provider is high-risk because it spawns the configured provider CLI and can reach external cloud APIs. args must be literal argv segments, not shell text. Use this when the provider name is dynamic.

• run_<provider> is the provider-specific version of run_provider. Use it when the provider is fixed and you want a narrower tool surface.

• get_command_limits is read-only. It returns the normalized command-limit policy currently loaded from the database.

• set_command_limit_section mutates the database and then force-pushes the current policy to the selected JSON target. Use supported provider aliases like gcloud, az, aliyun, doctl, tccli, or hcloud; the runtime normalizes them to canonical sections.

• replace_command_limits replaces the entire command-limit policy in the database and then force-pushes the JSON target. The payload must include the canonical sections aws.*, gcp.*, azure.*, oci.*, alibaba.*, digitalocean.*, ibmcloud.*, tencent.*, and huawei.*.

• push_command_limits does not change the database. It writes the current database-backed policy to the internal file or external source. pushTarget=auto prefers the external source when configured, otherwise the internal file.

• vault_seed_http_token generates a new bearer token, stores only its SHA-256 hash in the Vault token index, and returns the plaintext token once. Keep the returned token, because it cannot be recovered later.

• vault_seed_oauth_token stores a provided OAuth access token as a SHA-256 hash in the Vault token index and never returns the plaintext token.

Common prerequisites and constraints:

• discover_tools accepts optional query, tool, and limit. Use tool for exact schema lookup and query when you want ranked suggestions.

• Set MCP_PROVIDER_AUTH_KEY when you want provider vault and token-index admin tools to require authorizationKey.

• scopes and audience accept either a comma-separated string or an array of strings.

• expiresAt should be an ISO-8601 timestamp.

• path overrides the Vault token index path when you need a non-default location.

• Provider CLI resolution still follows the runtime order documented above: repository-local bin, <PROVIDER>_CLI_BIN, then PATH.

Example response shapes:

• discover_tools returns totalTools, returnedTools, and tools[], where each tool entry includes name, description, risk, recommendation, and JSON inputSchema.

• vault_seed_http_token returns token, tokenHash, tokenId, indexPath, and related entry fields.

• vault_seed_oauth_token returns tokenHash, tokenId, indexPath, and related entry fields.

Container note

This repository no longer ships a first-party Dockerfile, so it does not provide a built-in container image build path.

If your deployment requires containers, provide your own image definition around the Node entrypoints (node src/mcp.js for MCP mode, node src/index.js for CLI mode) and any cloud CLIs you want available in that runtime.

A sample container definition is available at docker/Containerfile.sample and can be used with either Docker or Podman:

docker build -f docker/Containerfile.sample -t cloud-mcp:local .
podman build -f docker/Containerfile.sample -t cloud-mcp:local .

Kubernetes (Helm) sample

A sample Helm chart is available at helm/cloud-mcp.

1. Build and push an image (Docker or Podman):

docker build -f docker/Containerfile.sample -t ghcr.io/your-org/cloud-mcp:latest .
docker push ghcr.io/your-org/cloud-mcp:latest

2. Copy chart values and edit for your environment:

cp helm/cloud-mcp/values.yaml helm/cloud-mcp/values.local.yaml

Set at minimum:

• image.repository

• image.tag

• env.VAULT_ADDR

• secrets.data.VAULT_TOKEN

• env.COMMAND_LIMITS_DATABASE_URL (or local-postgres toggle values)

3. Install or upgrade:

helm upgrade --install cloud-mcp ./helm/cloud-mcp -f helm/cloud-mcp/values.local.yaml

4. Verify:

kubectl rollout status deployment/cloud-mcp-cloud-mcp
kubectl logs deployment/cloud-mcp-cloud-mcp --tail=200

Notes:

• The chart mounts cloud-wrap.config.json from a ConfigMap at /etc/cloud-mcp/cloud-wrap.config.json.

• VAULT_TOKEN and MCP_PROVIDER_AUTH_KEY are provided by Kubernetes Secret (secrets.data).

• Default container args run MCP mode (mcp --config /etc/cloud-mcp/cloud-wrap.config.json).

Configuration

Create cloud-wrap.config.json using cloud-wrap.config.example.json as a template.

{
  "vault": {
    "module": "./external-vault.js",
    "options": {}
  },
  "providers": {
    "aws": {
      "command": "aws",
      "env": {
        "AWS_PROFILE": "default"
      },
      "defaultProfile": "default",
      "profileSupport": {
        "mode": "env",
        "envVar": "AWS_PROFILE"
      },
      "profiles": {
        "default": {
          "env": {
            "AWS_PROFILE": "default"
          },
          "users": []
        }
      }
    }
  }
}

If vault.module is present, the runtime will try to load that module first. The module should expose either createVault, a default factory, or a vault object with the same get/set/snapshot methods as the built-in service. If loading fails, the local in-memory vault is used.

This repo also includes a built-in external HashiCorp Vault adapter at src/core/hashicorpVault.js, mirrored after the akoya-mcp external vault setup. It is auto-selected when either:

• VAULT_PROVIDER=external

• both VAULT_ADDR and VAULT_TOKEN are set

Fail-closed behavior: when VAULT_PROVIDER=external and both VAULT_ADDR and VAULT_TOKEN are set, startup fails if the external vault module cannot be loaded or initialized. In this explicit external mode, it does not fall back to local in-memory vault.

CLOUD_WRAP_VAULT_MODULE still takes precedence over all auto-selection logic.

For external vault integrations, these environment variables are forwarded into the external vault options object when set:

• VAULT_PROVIDER

• VAULT_ADDR

• VAULT_TOKEN

• VAULT_NAMESPACE

• VAULT_KV_MOUNT

• VAULT_KV_VERSION

• VAULT_SECRET_PATH

• COMMAND_LIMITS_LOCAL_POSTGRES_ENABLED

• COMMAND_LIMITS_LOCAL_POSTGRES_PORT

Required vault key contract:

• Required environment variables for explicit external mode:

  • VAULT_PROVIDER=external

  • VAULT_ADDR

  • VAULT_TOKEN

• Required secret key at each provider path:

  • key name: provider

  • required object fields: command (string), env (object)

  • optional profile fields: defaultProfile (string), profiles (map), profileSupport (mode=arg|env, with flag or envVar)

  • optional per-profile access field: profiles.<name>.users (string array)

• Provider authorization key (when enabled):

  • set MCP_PROVIDER_AUTH_KEY to seed vault path mcp.authorization.providerKey

  • get_provider and set_provider requests must include authorizationKey matching that value

When using the built-in external adapter, VAULT_SECRET_PATH is treated as a base path and each cloud CLI provider is stored separately:

• ${VAULT_SECRET_PATH}/aws

• ${VAULT_SECRET_PATH}/gcp

• ${VAULT_SECRET_PATH}/azure

• ${VAULT_SECRET_PATH}/oci

• ${VAULT_SECRET_PATH}/alibaba

• ${VAULT_SECRET_PATH}/digitalocean

• ${VAULT_SECRET_PATH}/ibmcloud

• ${VAULT_SECRET_PATH}/tencent

• ${VAULT_SECRET_PATH}/huawei

Each provider secret stores one object at key provider containing command, env, and optional profile fields.

Multi-profile provider behavior:

• run_provider and run_<provider> accept optional profile.

• run_provider and run_<provider> accept optional user for profile access checks.

• If profile is provided, runtime applies profileSupport to inject profile context via args or env.

• profiles.<name>.args and profiles.<name>.env are merged into execution.

• profiles.<name>.users controls profile access:

  • empty or missing array means profile is available to all users

  • non-empty array restricts profile use to those users

• If profile is omitted and defaultProfile is configured, that profile is used.

CLOUD_WRAP_VAULT_MODULE can also be used to override vault.module from config.

For a ready-made external profile, use cloud-wrap.config.external-vault.example.json.

Then run:

npm start -- --config cloud-wrap.config.json aws sts get-caller-identity

Extend with additional providers

Add a provider in your config file:

{
  "providers": {
    "do": {
      "command": "doctl",
      "env": {
        "DIGITALOCEAN_ACCESS_TOKEN": "<token>"
      }
    }
  }
}

Then call:

npm start -- run do account get

Project structure

src/
  index.js            # entry point
  mcp.js              # MCP stdio entry point
  program.js          # command definitions
  core/
    context.js        # runtime context creation
    execute.js        # provider CLI spawning
    mcp.js            # MCP tool registration and server startup
  config/
    providers.js      # built-in provider defaults
    loadConfig.js     # config loading and validation
  utils/
    logger.js         # pino logger setup