Skip to main content
Glama
kunobi-ninja

Kunobi MCP Server

by kunobi-ninja
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

@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.

Kunobi

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

Kunobi — Cluster view

Related MCP server: hermes-platform-mcp

Setup

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

Kunobi — MCP settings

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

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:

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:

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):

npx @kunobi/mcp unpin

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.

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

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

Available Tools

2 tools
kunobi_callA

Stable tool entrypoint for Kunobi operations. Call a variant tool via (variant, tool, arguments), e.g. variant="dev", tool="k8s". Use kunobi://tools to discover full downstream tool schemas and metadata.

ParametersJSON Schema
NameRequiredDescriptionDefault
toolYesRemote tool name without variant prefix, e.g. "k8s".
variantYesKunobi variant name, e.g. "dev", "stable", "local".
argumentsNoArguments object passed to the target variant tool. Match the selected tool inputSchema from kunobi://tools.

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate it is not read-only, not destructive, and open world. The description adds that it calls variant tools, but does not disclose additional behaviors such as error handling or state changes. With annotations covering safety, this is adequate but not exceptional.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is highly concise with two sentences, front-loaded with the core purpose. Every sentence adds value without redundancy or excess.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the generic delegator nature, the description adequately explains how to use the tool and where to discover downstream schemas. It does not cover error cases or return behavior, but these are derivative of the called tool and thus acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%; each parameter has a description. The description adds an example and reference to kunobi://tools for full schemas, but does not significantly enhance understanding beyond the schema. For instance, it does not highlight that 'arguments' is optional.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is a stable entrypoint for Kunobi operations to call a variant tool via (variant, tool, arguments). It specifies the resource and action but does not explicitly differentiate from siblings like kunobi_launch, kunobi_refresh, and kunobi_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides an example and mentions using kunobi://tools for discovery, implying when to use this tool (to call a specific remote tool). However, it lacks explicit guidance on when not to use it or how it compares to sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kunobi_statusA
Read-only

Check which Kunobi variants are currently connected to this hub. Reports each variant's port, connection status, available tools, and reconnect timing. Call this before using Kunobi tools to understand what's available.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses specific behavioral details—reports port, connection status, available tools, and reconnect timing—beyond the annotations (readOnlyHint). No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, no waste. First sentence declares purpose, second lists outputs, third gives usage. Front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, good annotations, and lack of output schema, the description fully covers what the tool does, what it returns, and when to use it. Complete for its simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist (schema coverage 100%), so the description need not add parameter info. Baseline for 0 params is 4; description does not need to compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks which Kunobi variants are connected to the hub, using a specific verb ('Check') and resource. It distinguishes from siblings (call, launch, refresh) by focusing on connectivity status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly recommends calling this tool before using other Kunobi tools to understand what's available, providing strong usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.0.19
    • Removedkunobi_launch
    • Removedkunobi_refresh
  2. 2 tool updatesv0.0.15
    • Addedkunobi_call
    • Addedkunobi_refresh
  3. 2 tool updatesv0.0.1
    • First observedkunobi_launch
    • First observedkunobi_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored across 2 tools

Disambiguation5/5

Each tool has a clear and distinct purpose: 'kunobi_call' is for executing operations on variants, while 'kunobi_status' is for checking connection status and available tools. There is no overlap in functionality.

Naming Consistency5/5

Both tool names follow a consistent 'kunobi_<verb>' pattern (kunobi_call, kunobi_status), making them predictable and easy to understand.

Tool Count3/5

With only 2 tools, the server feels thin for a hub that presumably provides many downstream tools. However, the tools serve as a lightweight entry point, so the count is borderline acceptable.

Completeness4/5

The server covers the core lifecycle for a tool hub: discovery (via kunobi_call with 'kunobi://tools'), execution (kunobi_call), and status monitoring (kunobi_status). Missing are variant management tools like registration or shutdown, but these are minor gaps.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • veriloop

    arvindcr4
    A
    license
    A
    quality
    C
    maintenance
    Exposes a verified tool registry (calculator, sandboxed file read, web fetch) over MCP stdio, enabling any MCP-capable client to reuse the same tools from the inspectable ReAct loop.
    3
    MIT

  • mendix-marketplace-mcp-proxy

    joshuamoesa
    F
    license
    Not graded
    quality
    C
    maintenance
    MCP proxy that bridges Mendix Marketplace's Streamable HTTP endpoint to stdio, enabling Claude Code and other stdio-only MCP clients to access Mendix Marketplace tools and prompts dynamically.
    -