Skip to main content
Glama
vcluster-mcp

vcluster-mcp

by mmpyro

vcluster MCP Server

This is a Model Context Protocol (MCP) server that provides tools for managing vcluster instances. It allows AI assistants to list, describe, create, delete, pause, resume, export kubeconfigs, inspect control-plane certificates, and even execute commands inside virtual clusters.

Features

  • Lifecycle Management: Create (with full helm flag coverage - --set, multiple values files, chart pinning, --expose), delete, pause, resume, and disconnect vclusters.

  • Observability: List all vclusters and get detailed descriptions of specific instances.

  • Kubeconfig Export: Write a vcluster kubeconfig to a private (0600) temporary file and return its path, so credentials are never returned inline and the caller's kube context is left untouched.

  • Certificate Inspection: Read-only vcluster certs check for control-plane certificate expiry.

  • Remote Execution: Execute commands directly inside a vcluster context using the vcluster connect mechanism.

  • Namespace Metadata: Manage labels and annotations on Kubernetes namespaces associated with vclusters.

  • Read-only Resources: Browse the environment through vcluster:// URIs without invoking a tool.

  • Low context cost: The advertised tool surface is 8,868 chars (~2.5k tokens), down from 29,035. Responses are compact JSON, sent once rather than twice, and hard-capped. A regression test holds the line.

Related MCP server: Kube MCP

Documentation

Full documentation lives in docs/:

  • Tools — all 12 operations, their parameters and safety notes

  • Resources — the 2 read-only vcluster:// URIs

  • Architecture — how a call flows through the code, and how to add a tool

Fixes

  • vcluster_certs_check never worked. It passed -s to the CLI, and --silent suppresses the JSON result itself rather than just the log noise, so every call returned {"error": "Failed to parse vcluster output: ..."}. The flag is gone; the CLI already logs to stderr.

  • _run_command discarded stdout on any non-zero exit, so a command that partially succeeded lost its output. It now prefers stdout whenever the process wrote any.

Breaking changes

  • Tools return a JSON string, not a structured object. Every tool is now registered with structured_output=False, so responses arrive as a single compact text block with no structuredContent. Clients that read the structured half must parse the text instead.

  • The six namespace label/annotation tools are now two. get/set/delete_namespace_label and get/set/delete_namespace_annotation are replaced by namespace_metadata_get(namespace, kind) and namespace_metadata_set(namespace, kind, key, value), where omitting value deletes the key.

  • All six prompts were removed. Their bodies re-listed the tool schemas the client already loads.

  • vcluster://clusters and vcluster://{namespace}/{name} were removed. They duplicated vcluster_list and vcluster_describe.

  • vcluster_list drops the Created field by default, since AgeSeconds carries the same fact; pass full=True to get it back.

  • Responses are capped at 20,000 chars (2,000 for stderr inside an error message), with an explicit [truncated: N more chars] marker.

  • vcluster_delete no longer deletes the host namespace by default. Previously every delete passed --delete-namespace, which destroyed the namespace along with any unrelated workloads in it. The namespace is now preserved unless you pass delete_namespace=True; vcluster still cleans up namespaces it created itself.

Project Structure

The project follows a modular structure optimized for MCP:

  • src/: Core application source code.

    • tools/: MCP tool implementations (vcluster operations, namespace metadata).

    • resources/: Read-only vcluster:// resources for browsing clusters, certificates and namespace metadata.

    • utils/: Shared utilities, Kubernetes client setup, and vcluster manager.

    • tests/: Comprehensive unit tests for the server logic.

  • docs/: Tool, resource and architecture documentation.

  • pyproject.toml: Project configuration and dependency management via uv.

Prerequisites

To run this MCP server and manage vclusters, you need the following:

1. Python Environment

This project uses uv for dependency management. See Development Commands for installation.

2. vcluster CLI

vcluster CLI must be installed on your system and available in your PATH.

3. kubectl

kubectl must be installed and configured with access to the host Kubernetes cluster where vclusters are running.

Development Commands

For convenience, a Makefile is provided with common tasks:

  • Sync dependencies:

    make sync      # Production only
    make sync-dev  # Include dev dependencies
  • Running tests:

    make unittest          # Run unit tests only
    make test-cov          # Run tests with coverage report
  • Quality Checks:

    make lint              # Run flake8 linting
    make typecheck         # Run mypy type checking
    make check             # Run both linting and type checking
  • Local Development:

    make dev               # Start server in development mode

Configuration for Cloud Code / Claude Desktop

To use this MCP server, add the following configuration to your mcpServers setting:

Local path

Important: Before using this MCP server, you need to install the dependencies. Run this command in the project root:

uv sync

Then add the following configuration to your MCP settings:

{
  "mcpServers": {
    "vcluster": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "~/vcluster-mcp-server",
        "run",
        "python",
        "src/server.py"
      ],
      "env": {}
    }
  }
}

uvx

uvx is a uv subcommand for running Python tools in an isolated, cached environment.

Example configuration:

{
  "mcpServers": {
    "vcluster": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "git+https://github.com/mmpyro/vcluster-mcp-server.git"
      ]
    }
  }
}

Contributing

Unit tests are located in src/tests. Please ensure all tests pass before submitting changes.

Available Tools

12 tools
namespace_metadata_getB

Read labels and/or annotations on a namespace.

Inputs: namespace (required), kind, kubeconfig_path.

namespace_metadata_setA

Set or delete one label or annotation on a namespace.

Deleting a key that does not exist succeeds.

Inputs: key (required), kind (required), namespace (required), value, +1 more.

vcluster_callB

Run a command inside a vcluster via vcluster connect.

Output is capped; prefer narrow queries over -o yaml across all namespaces.

Inputs: name (required), command (required), namespace, kubeconfig_path.

vcluster_certs_checkA

Report control-plane certificates and expiry for a vcluster.

Read-only. Worth checking when a vcluster looks healthy but is unreachable, since expired certs surface as opaque connection failures.

Inputs: name (required), namespace, kubeconfig_path.

vcluster_createB

Create a vcluster. Never switches the caller's kube context.

Inputs: name (required), expose, values, upgrade, +8 more.

vcluster_deleteB

Delete a vcluster. Irreversible. The host namespace is preserved by default.

Inputs: name (required), wait, keep_pvc, namespace, +3 more.

vcluster_describeB

Status, resources and configuration of one vcluster. Namespace defaults to vcluster-.

Inputs: name (required), namespace, kubeconfig_path.

vcluster_disconnectB

Disconnect from the currently connected vcluster.

Inputs: kubeconfig_path.

vcluster_kubeconfigA

Export a vcluster kubeconfig without switching the caller's context.

Returns the path to a private (0600) temp file, not the contents, because it holds client credentials. Pass the path to other tools; delete it after use.

Inputs: name (required), server, insecure, namespace, +1 more.

vcluster_listB

List all vclusters in the current Kubernetes context.

Inputs: full, kubeconfig_path.

vcluster_pauseA

Pause a running vcluster, stopping its workloads without deleting state.

Inputs: name (required), namespace, kubeconfig_path.

vcluster_resumeC

Resume a paused vcluster.

Inputs: name (required), namespace, kubeconfig_path.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing, describing, checking certs, exporting kubeconfig, pausing/resuming, creating, executing commands, deleting, disconnecting, and managing namespace metadata. There is no overlap that would cause misselection, and the two namespace metadata tools are cleanly separated by get/set.

    Naming Consistency4/5

    Most tools follow a clean vcluster_<verb> pattern (list, describe, pause, resume, create, call, delete, disconnect). Minor deviations exist: vcluster_certs_check (noun-verb), vcluster_kubeconfig (noun only), and the namespace_metadata_get/set pair uses a different prefix. These are readable but not perfectly uniform.

    Tool Count5/5

    With 12 tools, the server is well-scoped for vcluster management. Each tool provides a necessary operation, and the count is comfortably within the ideal 3-15 range, neither bloated nor thin.

    Completeness4/5

    The toolset covers the full vcluster lifecycle (create, list, describe, delete, pause/resume) plus operational utilities (certs, kubeconfig, command execution, disconnect). Minor gaps exist: no update/modify tool for vcluster configuration and no explicit connect tool to pair with disconnect, though kubeconfig and call can serve access needs.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to interact with and manage Kubernetes clusters, supporting operations on pods, deployments, services, configmaps, secrets, namespaces, metrics, and events with built-in safety features for destructive actions.
      9
      10 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to manage VMware vSphere infrastructure through 55 typed tools built on the govc CLI. It supports comprehensive operations including VM lifecycle management, snapshot control, datastore navigation, and networking configuration.
      5
      -