nebula-mcp

MCP server for the Nebula Control Plane API. Install via npm — no clone or local build required.

Quick start

Add one entry to your MCP config (Claude Desktop, Claude Code .mcp.json, or Cursor):

{
  "mcpServers": {
    "nebula": {
      "command": "npx",
      "args": ["-y", "@andinolabs/nebula-mcp"],
      "env": {
        "NEBULA_API_URL": "https://admin.nebula.andinolabs.ai"
      }
    }
  }
}

npx -y fetches and caches the package on first use.

Or via Claude Code CLI:

claude mcp add nebula -- npx -y @andinolabs/nebula-mcp

Set NEBULA_API_URL in the environment when adding if your control plane URL differs.

Environment variables

| Var | Default | Description | |---|---|---| | NEBULA_API_URL | http://localhost:8080 | Nebula Control Plane base URL | | NEBULA_API_TOKEN | (empty) | Bearer token for headless/CI (optional) |

Authentication

Interactive login (default)

When NEBULA_API_TOKEN is not set, the server opens your browser to complete an OAuth 2.0 + PKCE login on the first request. Tokens are persisted to ~/.config/nebula/tokens.json and refreshed automatically. The browser only re-opens when the refresh token expires (~30–90 days).

Headless / CI

Set NEBULA_API_TOKEN to a long-lived API key. This bypasses the browser flow entirely and no token file is read or written.

Tools exposed

| Tool | Domain | |---|---| | login | Auth | | health_check | Health | | list_apps / get_app | Platform apps | | list_clusters / get_cluster | Platform clusters | | list_tenants / get_tenant / create_tenant | Catalog – Tenants | | get_tenant_github_status / list_tenant_github_repos | Catalog – GitHub | | get_tenant_jira_status / list_tenant_jira_projects | Catalog – Jira | | list_environments / get_environment | Catalog – Environments | | list_applications / get_application | Catalog – Applications | | list_application_jira_issues | Catalog – Jira Issues | | list_cd_clusters / get_cd_cluster | CD – Clusters | | list_cd_pipelines / get_cd_pipeline | CD – Pipelines | | list_cloud_providers | Cloud – Providers | | list_cloud_resources / provision_cloud_resource / preview_terraform | Cloud – Resources | | list_capture_topics / get_capture_topic | Capture – Topics | | list_capture_sessions / get_capture_session_summary | Capture – Sessions |

Development

For contributors working from this repository:

pnpm install
pnpm run build

Register a local build in MCP config:

{
  "mcpServers": {
    "nebula": {
      "command": "node",
      "args": ["/absolute/path/to/claude-mcp/dist/index.js"],
      "env": {
        "NEBULA_API_URL": "http://localhost:8080"
      }
    }
  }
}

Hot-reload during development:

NEBULA_API_URL=http://localhost:8080 pnpm run dev

Publishing

Published to the public npm registry under @andinolabs (@andinolabs/nebula-mcp).

Publishing uses an npm access token only — no interactive login or 2FA OTP at publish time.

Create a publish token (one-time)

1. Join the andinolabs org on npm with publish permission.
2. Open Access Tokens → Generate New Token → Granular Access Token.
3. Configure:
   • Organizations: andinolabs — Read and write
   • Packages: @andinolabs/nebula-mcp (or all org packages)
   • Expiration: per your security policy
   • Bypass 2FA for automation: enabled (required for non-interactive publish)
4. Copy the token (npm_…) — it is shown only once.

Store the token in your password manager or CI secret NPM_TOKEN. Never commit it.

Publish locally

export NPM_TOKEN=npm_xxxxxxxx
just publish

CI

Set the same granular token as the NPM_TOKEN repository/organization secret; the publish recipe writes a temporary .npmrc and removes it on exit.