vcluster管理MCP服务器

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.

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.