vcluster-mcp
This MCP server manages vcluster virtual clusters and their Kubernetes host namespaces.
List and inspect: List all vclusters and get detailed descriptions of individual clusters.
Lifecycle: Create vclusters with Helm values, chart pinning, upgrade/expose options; delete with flags like delete_namespace, keep_pvc, ignore_not_found, and wait; pause and resume clusters.
Connectivity: Export a vcluster kubeconfig to a private temp file and return its path; run commands inside a vcluster with vcluster_call; disconnect from a vcluster.
Certificate checking: Read-only certificate expiry check for control-plane certificates.
Namespace metadata: Get, set, and delete labels and annotations on host namespaces.
Read-only resources: Browse vcluster information via vcluster:// URIs.
Provides tools for managing vcluster virtual clusters on Kubernetes, including lifecycle operations (create, delete, pause, resume), listing and describing clusters, exporting kubeconfigs, checking certificates, executing commands inside virtual clusters, and managing Kubernetes namespace labels and annotations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vcluster-mcp list all vclusters"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 checkfor control-plane certificate expiry.Remote Execution: Execute commands directly inside a vcluster context using the
vcluster connectmechanism.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://URIsArchitecture — how a call flows through the code, and how to add a tool
Fixes
vcluster_certs_checknever worked. It passed-sto the CLI, and--silentsuppresses 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_commanddiscarded 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 nostructuredContent. Clients that read the structured half must parse the text instead.The six namespace label/annotation tools are now two.
get/set/delete_namespace_labelandget/set/delete_namespace_annotationare replaced bynamespace_metadata_get(namespace, kind)andnamespace_metadata_set(namespace, kind, key, value), where omittingvaluedeletes the key.All six prompts were removed. Their bodies re-listed the tool schemas the client already loads.
vcluster://clustersandvcluster://{namespace}/{name}were removed. They duplicatedvcluster_listandvcluster_describe.vcluster_listdrops theCreatedfield by default, sinceAgeSecondscarries the same fact; passfull=Trueto 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_deleteno 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 passdelete_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-onlyvcluster://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 viauv.
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 dependenciesRunning tests:
make unittest # Run unit tests only make test-cov # Run tests with coverage reportQuality Checks:
make lint # Run flake8 linting make typecheck # Run mypy type checking make check # Run both linting and type checkingLocal 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 syncThen 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 toolsnamespace_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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Create, run and manage Homemade dev VMs and projects from your AI agent.
Manage Vozora VPS servers, SSH keys, firewalls, DNS and usage from an AI agent.
Manage Rackspace Spot Kubernetes Cloudspaces, node pools, and VMs from your AI assistant.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables managing Kubernetes clusters through natural language by providing tools to list resources, view logs, port-forward services, scale deployments, and execute kubectl operations via AI assistants.81MIT
- AlicenseAqualityDmaintenanceEnables 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.910 npm1MIT
- FlicenseNot gradedqualityCmaintenanceEnables 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-
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to query, validate, and create vCluster YAML configurations directly from GitHub, supporting version-specific queries and automatic validation.40 npm-