@kunobi/mcp

MCP bridge to Kunobi, a desktop platform management IDE. AI assistants manage Kubernetes, FluxCD, ArgoCD, and Helm while users maintain real-time visual oversight.

What is Kunobi?

Kunobi is a desktop IDE for platform engineering — built with Rust and React, no Electron.

• Real-time cluster visibility with resource browser, YAML editor, and embedded terminal

• Native FluxCD, ArgoCD, and Helm support

• Built-in MCP server for AI assistants (Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI, GitHub Copilot CLI)

• Available on macOS, Windows, and Linux

• No account required, no cloud dependency

Setup

Enable MCP in Kunobi under Settings > AI & MCP, then install:

Automatic (recommended)

Register with all your AI clients in one step:

npx @kunobi/mcp --install

This interactively detects your installed AI clients and registers the server with them. Supported clients:

• Claude Code — project or user scope

• Claude Desktop — user scope

• Cursor — project or user scope

• Windsurf — project or user scope

• Codex CLI — project or user scope

• Gemini CLI — project or user scope

• GitHub Copilot CLI — user scope

To remove the server from all clients:

npx @kunobi/mcp --uninstall

Manual

If you prefer manual setup, add the following to your client's MCP config:

{
  "mcpServers": {
    "kunobi": {
      "command": "npx",
      "args": ["-y", "@kunobi/mcp"]
    }
  }
}

How it works

AI assistant <--stdio--> @kunobi/mcp <--HTTP--> Kunobi variants
                          │
                          ├── keeps one MCP connection per configured variant
                          ├── retries disconnected variants every 5s
                          └── manages one bundler per variant

The server keeps a persistent MCP connection for each configured Kunobi variant. When a variant is available, its tools are registered with a variant__ prefix (e.g., dev__list_clusters, stable__query_store). When a variant briefly drops, the hub keeps the last-known surface stable while it reconnects in the background. If the disconnect outlives the reconnect grace window, the stale registrations are removed.

Multi-variant support

Kunobi ships multiple release channels that run on different ports. This MCP server discovers all of them simultaneously:

These defaults are auto-generated into ~/.config/kunobi/mcp.json on first run. You can add custom variants or change ports — see Configuration.

Built-in tools

These are always available, even when no Kunobi instance is running:

• kunobi_status — reports all variant connection states, ports, and tool counts

• kunobi_launch — launches a Kunobi variant by name

• kunobi_refresh — forces an immediate reconnect attempt across all configured variants

• kunobi_call — stable entrypoint for variant tools (variant, tool, arguments)

Recommended calling pattern

Use the stable path below for the most reliable MCP client behavior:

1. Call kunobi_status

2. Read kunobi://tools to discover full downstream tool schemas and metadata

3. Execute via kunobi_call(variant, tool, arguments)

Dynamic tools

When a Kunobi variant is detected, its tools appear automatically with a variant prefix. For example, if dev and stable are both running:

• dev__app_info, dev__query_store, dev__list_stores, ...

• stable__app_info, stable__query_store, stable__list_stores, ...

Tools appear dynamically as variants start, and they are withdrawn only after a sustained disconnect — no MCP server restart needed.

These dynamic variant__tool entries are still supported, but some MCP clients may not refresh dynamic tool lists reliably. Use kunobi_call as the primary path when in doubt.

Resources

Resources exposed by Kunobi variants are proxied through automatically. When a variant connects, its resources become available to the AI client with variant-namespaced URIs to avoid collisions between multiple running variants.

The server also provides built-in resources:

• kunobi://status — JSON snapshot of all variant connection states, ports, and capability counts. Supports subscriptions — clients receive notifications/resources/updated whenever variants connect or disconnect.

• kunobi://tools — JSON discovery document listing each variant status plus full downstream tool, resource, and prompt metadata for kunobi_call.

Prompts

Prompts from Kunobi variants are registered with a variant__ prefix (e.g., dev__setup_cluster). They appear and disappear alongside their variant, just like tools.

Configuration

Config file

Variant-to-port mappings are stored in ~/.config/kunobi/mcp.json (auto-generated on first run with defaults). You can edit this file directly or use the CLI:

# List all configured variants and their connection status
kunobi-mcp list

# Add a custom variant
kunobi-mcp add juan 4200

# Remove a variant
kunobi-mcp remove juan

Environment variables

Priority: config file defaults → MCP_KUNOBI_VARIANTS env var (merges on top).

CLI

kunobi-mcp [command] [options]

Development

pnpm install
pnpm build
pnpm test

For local development against @kunobi/mcp-bundler:

pnpm dev:link    # link local bundler
pnpm dev:unlink  # revert to npm version

License

Apache-2.0