@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)
• 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

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:

Variant	Default port	Tool prefix
legacy	3030	legacy__
stable	3200	stable__
unstable	3300	unstable__
dev	3400	dev__
local	3500	local__
e2e	3600	e2e__

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

Env var	Default	Description
MCP_KUNOBI_RECONNECT_INTERVAL_MS	5000	Reconnect interval in ms
MCP_KUNOBI_VARIANTS	—	name:port pairs to merge (e.g., juan:4200,test:5000)
MCP_KUNOBI_AUTO_CONNECT	true	Set false to disable automatic background connections. kunobi_refresh still works for manual retries.

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

CLI

kunobi-mcp [command] [options]

Command	Description
list	Show configured variants and connection status
add <name> <port>	Add or update a variant
remove <name>	Remove a variant
install	Register this MCP server with your AI clients
uninstall	Remove this MCP server from your AI clients
--help, -h	Show help message
--version, -v	Show version number
(no command, piped)	Start the stdio MCP server (used by AI clients)

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