@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:```bash
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:```bash
npx @kunobi/mcp --uninstall
Updating
install 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:```bash
npx @kunobi/mcp upgrade
This 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:```bash
npx @kunobi/mcp pin
If 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):```bash
npx @kunobi/mcp unpin
### Manual
If you prefer manual setup, add the following to your client's MCP config:```json
{
"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:```bash
# 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. |
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).
CLI```
kunobi-mcp [command] [options]
| Command | Description |
|---------|-------------|
| `list` | Show configured variants and connection status |
| `add ` | Add or update a variant |
| `remove ` | 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) |
## Development```bash
pnpm install
pnpm build
pnpm test
For local development against @kunobi/mcp-bundler:bash
pnpm dev:link # link local bundler
pnpm dev:unlink # revert to npm version
License
Apache-2.0
