MCP bridge to Kunobi, a desktop platform management IDE. AI assistants manage Kubernetes, FluxCD, ArgoCD, and Helm while users maintain real-time visual oversight.
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
Enable MCP in Kunobi under Settings > AI & MCP, then install:
Register with all your AI clients in one step:
npx @kunobi/mcp --installThis 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 --uninstallinstall pins your clients to an exact version (e.g. @kunobi/mcp@1.2.3) so each
launch runs from the npm cache instead of resolving latest from the registry on
every spawn — startup stays fast and can't stall on the network. When a newer
version is published, the server tells you on connect; apply it with:
npx @kunobi/mcp upgradeThis re-pins every client where Kunobi is registered to the newest version and warms the cache. Restart your AI client to load it (the new version takes effect on the next start).
Installed before pinning existed? Pin your current version in place — no upgrade, no registry call:
npx @kunobi/mcp pinIf you ran an older build, the server also hints this on connect when it detects
an unpinned config. Silence the hint with MCP_KUNOBI_NO_PIN_HINT=1.
Prefer always-latest? Opt back out — each launch will resolve the newest version again (slower startup, and can stall on the registry):
npx @kunobi/mcp unpinIf you prefer manual setup, add the following to your client's MCP config:
{
"mcpServers": {
"kunobi": {
"command": "npx",
"args": ["-y", "@kunobi/mcp"]
}
}
}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.
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.
These are always available, even when no Kunobi instance is running:
kunobi_status— reports all variant connection states, ports, and tool countskunobi_launch— launches a Kunobi variant by namekunobi_refresh— forces an immediate reconnect attempt across all configured variantskunobi_call— stable entrypoint for variant tools (variant,tool,arguments)
Use the stable path below for the most reliable MCP client behavior:
- Call
kunobi_status - Read
kunobi://toolsto discover full downstream tool schemas and metadata - Execute via
kunobi_call(variant, tool, arguments)
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 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 receivenotifications/resources/updatedwhenever variants connect or disconnect.kunobi://tools— JSON discovery document listing each variant status plus full downstream tool, resource, and prompt metadata forkunobi_call.
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.
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| 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. |
MCP_KUNOBI_NO_PIN_HINT |
— | Set 1 to suppress the startup hint that suggests pinning an unpinned install. |
Priority: config file defaults → MCP_KUNOBI_VARIANTS env var (merges on top).
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 (pinned to the current version) |
uninstall |
Remove this MCP server from your AI clients |
pin |
Pin your AI clients to the current version (faster, hang-proof startup) |
unpin |
Revert to always-latest (npx -y @kunobi/mcp; slower startup) |
upgrade |
Re-pin your AI clients to the latest published version (restart to apply) |
--help, -h |
Show help message |
--version, -v |
Show version number |
| (no command, piped) | Start the stdio MCP server (used by AI clients) |
pnpm install
pnpm build
pnpm testFor local development against @kunobi/mcp-bundler:
pnpm dev:link # link local bundler
pnpm dev:unlink # revert to npm version