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", "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 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

From this directory:

# npm automation token, or `npm login` beforehand
export NPM_TOKEN=<token>
just publish

CI on version tags (v*) runs the same steps (pnpm install, pnpm build, npm publish) using an NPM_TOKEN secret.