K8s MCP Server

K8s MCP Server is a server for Anthropic's MCP (Model Context Protocol) that allows running Kubernetes CLI tools such as kubectl, istioctl, helm, and argocd in a safe, containerized environment.

Overview

K8s MCP Server acts as a secure bridge between language models (like Claude) and Kubernetes CLI tools. It enables language models to execute validated Kubernetes commands, retrieve command documentation, and process command output in a structured way.

Demo: Deploy and Troubleshoot WordPress

Session 1: Using k8s-mcp-server and Helm CLI to deploy a WordPress application in the claude-demo namespace, then intentionally breaking it by scaling the MariaDB StatefulSet to zero.

Session 2: Troubleshooting session where we use k8s-mcp-server to diagnose the broken WordPress site through kubectl commands, identify the missing database issue, and fix it by scaling up the StatefulSet and configuring ingress access..

Demo

Architecture

K8s MCP Server is designed with a focus on security, performance, and extensibility. The system comprises the following core components:

flowchart TD
    A[AI Assistant] <-->|HTTP/WebSocket<br>MCP Protocol| B[FastMCP Server]
    B --> C[Tool Registration<br>Logging & Context]
    B --> D[Prompt Templates]
    C --> E[Command Validation]
    E --> F[CLI Executor]
    F --> G[Tool-specific Handlers]
    G --> H[kubectl]
    G --> I[helm]
    G --> J[istioctl]
    G --> K[argocd]
    F --> L[Security Validator]

    classDef core fill:#f9f,stroke:#333,stroke-width:2px
    classDef tools fill:#bbf,stroke:#333,stroke-width:1px
    classDef security fill:#fbb,stroke:#333,stroke-width:1px

    class B,C,D,F core
    class G,H,I,J,K tools
    class E,L security

Core Components

1. Server Component: Central controller that initializes the MCP server, registers tools and prompts, and handles client requests.

2. Security Validator: Checks command structure and content to prevent potentially dangerous operations, enforcing strict validation rules.

3. CLI Executor: Manages command execution, timeout handling, and output processing for all Kubernetes CLI tools.

4. Tool-specific Handlers: Specialized functions for each supported tool (kubectl, helm, istioctl, argocd) that provide appropriate command preprocessing and response formatting.

5. Prompt Templates: Pre-defined natural language templates for common Kubernetes operations to improve language model interactions.

Command Execution Flow

The following diagram illustrates how commands flow through the system:

sequenceDiagram
    participant LM as Language Model
    participant MCP as MCP Server
    participant Val as Security Validator
    participant Exec as CLI Executor
    participant K8s as K8s CLI Tools

    LM->>MCP: Tool request via MCP
    MCP->>Val: Validate command

    alt Invalid Command
        Val-->>MCP: Validation error
        MCP-->>LM: Error response
    else Valid Command
        Val->>Exec: Execute command
        Exec->>K8s: Run CLI tool
        K8s-->>Exec: Command output
        Exec-->>MCP: Formatted response
        MCP-->>LM: Success response
    end

1. The language model sends a command request via the MCP protocol.
2. The server validates the command using security rules.
3. If valid, the command is executed with the appropriate CLI tool.
4. Results or errors are captured and formatted into a structured response.
5. The response is returned to the language model.

Features

• Execute Kubernetes CLI commands securely with proper validation, timeouts and error handling
• Support for multiple Kubernetes CLI tools:
• kubectl: Kubernetes command-line tool
• istioctl: Command-line tool for Istio service mesh
• helm: Kubernetes package manager
• argocd: GitOps continuous delivery tool for Kubernetes
• Command piping capabilities with popular Linux CLI tools
• Detailed command validation and safety checks
• Configurable timeouts and output limits
• Comprehensive documentation and help retrieval
• Context and namespace management
• Pre-built prompt templates for common Kubernetes operations

Requirements

To use K8s MCP Server with Claude Desktop, you need:

• Docker installed on your system
• Valid Kubernetes configuration in ~/.kube/config
• Claude Desktop application

Configuration

K8s MCP Server can be configured via environment variables that can be passed to the Docker container:

| Environment Variable | Description | Default | Required | |----------------------|-------------|---------|----------| | K8S_MCP_TIMEOUT | Default timeout for commands (seconds) | 300 | No | | K8S_MCP_MAX_OUTPUT | Maximum output size (characters) | 100000 | No | | K8S_MCP_TRANSPORT | Transport protocol to use ("stdio" or "sse") | stdio | No | | K8S_CONTEXT | Kubernetes context to use | current context | No | | K8S_NAMESPACE | Default Kubernetes namespace | default | No | | K8S_MCP_SECURITY_MODE | Security mode ("strict" or "permissive") | strict | No | | K8S_MCP_SECURITY_CONFIG | Path to security configuration YAML file | None | No |

For example, to use specific context and namespace, modify your Claude Desktop configuration:

{
  "mcpServers": {
    "k8s-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "~/.kube:/home/appuser/.kube:ro",
        "-e",
        "K8S_CONTEXT=my-cluster",
        "-e",
        "K8S_NAMESPACE=my-namespace",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

Using Custom Security Configuration

To use a custom security configuration file, mount it into the container and set the environment variable:

{
  "mcpServers": {
    "k8s-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "~/.kube:/home/appuser/.kube:ro",
        "-v",
        "/path/to/my-security-config.yaml:/app/security_config.yaml:ro",
        "-e",
        "K8S_MCP_SECURITY_CONFIG=/app/security_config.yaml",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

Running in Permissive Mode

To run in permissive mode (allow all commands, including potentially dangerous ones):

{
  "mcpServers": {
    "k8s-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "~/.kube:/home/appuser/.kube:ro",
        "-e",
        "K8S_MCP_SECURITY_MODE=permissive",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

Integrating with Claude Desktop

To integrate K8s MCP Server with Claude Desktop, follow these steps:

1. Locate the Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

1. Edit the configuration file to include the K8s MCP Server:

   {
     "mcpServers": {
       "kubernetes": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-v",
           "~/.kube:/home/appuser/.kube:ro",
           "ghcr.io/alexei-led/k8s-mcp-server:latest"
         ]
       }
     }
   }

Note: Make sure to replace ~/.kube with the absolute path to your Kubernetes configuration directory, and update the image name if using a custom image.

3. Restart Claude Desktop to apply the changes

• After restarting, you should see a hammer 🔨 icon in the bottom right corner of the input box
• This indicates that the K8s MCP Server is available for use

flowchart TD
    subgraph "User Device"
        config[Edit claude_desktop_config.json]
        claude[Claude Desktop]
        docker[Docker Container]
        k8s_config[Kubernetes Config]
    end

    subgraph "Kubernetes Cluster"
        k8s[Kubernetes Services]
    end

    config -->|Add MCP Server Config| claude
    claude -->|Docker Run Command| docker
    k8s_config -->|Mount Read-only| docker
    docker -->|kubectl & other CLI tools| k8s

Using Kubernetes Tools in Claude

Once configured, you can ask Claude to perform Kubernetes operations:

• "Show me the pods in my default namespace using kubectl"
• "Help me deploy a new application with Helm"
• "Check the status of my Istio service mesh"
• "List all my Kubernetes deployments"

Claude will automatically use the appropriate Kubernetes CLI tools via the K8s MCP Server.

## API Reference

The server implements the [Model Context Protocol (MCP)](https://docs.anthropic.com/en/docs/agents-and-tools/model-context-protocol-mcp/) and provides the following tools:

### Documentation Tools

Each Kubernetes CLI tool has its own documentation function:

- `describe_kubectl(command=None)`: Get documentation for kubectl commands
- `describe_helm(command=None)`: Get documentation for Helm commands
- `describe_istioctl(command=None)`: Get documentation for Istio commands
- `describe_argocd(command=None)`: Get documentation for ArgoCD commands

### Execution Tools

Each Kubernetes CLI tool has its own execution function:

- `execute_kubectl(command, timeout=None)`: Execute kubectl commands
- `execute_helm(command, timeout=None)`: Execute Helm commands
- `execute_istioctl(command, timeout=None)`: Execute Istio commands
- `execute_argocd(command, timeout=None)`: Execute ArgoCD commands

### Command Piping

All execution tools support Unix command piping to filter and transform output:

python executekubectl(command="get pods -o json | jq '.items[].metadata.name'") executehelm(command="list | grep nginx")

### Configuration Options

#### Environment Variables

| Variable | Description | Default | Notes |
|----------|-------------|---------|-------|
| `K8S_MCP_TIMEOUT` | Command execution timeout (seconds) | 300 | Applies to all commands |
| `K8S_MCP_MAX_OUTPUT` | Maximum output size (characters) | 100000 | Truncates output if exceeded |
| `K8S_MCP_TRANSPORT` | Transport protocol | "stdio" | "stdio" or "sse" |
| `K8S_CONTEXT` | Kubernetes context | current | Uses kubectl current-context if empty |
| `K8S_NAMESPACE` | Default namespace | "default" | Applied to all commands |
| `K8S_MCP_SECURITY_MODE` | Security validation mode | "strict" | "strict" or "permissive" |
| `K8S_MCP_SECURITY_CONFIG` | Path to security config file | None | YAML configuration file |

#### Security Configuration File Format

The security configuration file uses YAML format with the following structure:

yaml

Dangerous command prefixes (prefix-based matching)

dangerous_commands: kubectl: - "kubectl delete" - "kubectl drain" # …more dangerous commands

Safe pattern exceptions (prefix-based matching)

safe_patterns: kubectl: - "kubectl delete pod" - "kubectl delete deployment" # …more safe patterns

Advanced regex pattern rules

regexrules: kubectl: - pattern: "kubectl\s+delete\s+(-[A-Za-z]+\s+)*--all\b" description: "Deleting all resources of a type" errormessage: "Custom error message shown to the user" # …more regex rules

## Supported Tools and Commands

### kubectl

Execute and manage Kubernetes resources:

kubectl get pods kubectl get deployments kubectl describe pod my-pod

### istioctl

Manage Istio service mesh configuration:

istioctl analyze istioctl proxy-status istioctl dashboard

### helm

Manage Helm charts and releases:

helm list helm install my-release my-chart helm upgrade my-release my-chart

### argocd

Manage ArgoCD applications:

argocd app list argocd app get my-app argocd app sync my-app

## Testing

K8s MCP Server includes comprehensive test coverage with both unit and integration tests. The testing architecture is designed to be lightweight, fast, and representative of real-world usage.

mermaid flowchart TD A[Testing Framework] --> B[Unit Tests] A --> C[Integration Tests] B --> D[Mock Executor] B --> E[Validation Tests] B --> F[Security Tests] C --> G[KWOK Cluster] C --> H[Local Cluster]

classDef unit fill:#bbf,stroke:#333,stroke-width:1px
classDef integ fill:#fbb,stroke:#333,stroke-width:1px

class B,D,E,F unit
class C,G,H integ

### Running Integration Tests

Integration tests validate the command execution and response handling of k8s-mcp-server. By default, the tests use KWOK (Kubernetes Without Kubelet) to create a lightweight simulated Kubernetes cluster for testing.

#### Prerequisites

Integration tests require:
- `kubectl` installed and in your PATH
- `kwokctl` installed for the default KWOK-based testing (see below)
- Optional: `helm` for Helm-related tests
- Optional: A real Kubernetes cluster for advanced testing scenarios

#### Option 1: Using KWOK (Recommended)

[KWOK (Kubernetes Without Kubelet)](https://kwok.sigs.k8s.io/) provides a lightweight simulation of a Kubernetes cluster without requiring actual node or container execution. This is the default and recommended approach for running the integration tests.

1. **Install KWOK**:

bash # For macOS with Homebrew: brew install kwokctl

# For Linux or manual installation: KWOKVERSION=$(curl -s https://api.github.com/repos/kubernetes-sigs/kwok/releases/latest | grep tagname | cut -d '"' -f 4) curl -Lo kwokctl https://github.com/kubernetes-sigs/kwok/releases/download/${KWOKVERSION}/kwokctl-$(go env GOOS)-$(go env GOARCH) curl -Lo kwok https://github.com/kubernetes-sigs/kwok/releases/download/${KWOKVERSION}/kwok-$(go env GOOS)-$(go env GOARCH) chmod +x kwokctl kwok sudo mv kwokctl kwok /usr/local/bin/

2. **Run Integration Tests**:

bash # Run all integration tests (KWOK cluster will be created automatically) pytest tests/integration -v

# Run specific test pytest tests/integration/testk8stools.py::testkubectlversion -v

# Skip cleanup of KWOK cluster for debugging K8SSKIPCLEANUP=true pytest tests/integration -v

The test framework will:
1. Automatically create a KWOK cluster for your tests
2. Run all integration tests against this cluster
3. Delete the cluster when tests complete (unless `K8S_SKIP_CLEANUP=true`)

Benefits of using KWOK:
- Extremely lightweight (no real containers or nodes)
- Fast startup and shutdown (seconds vs. minutes)
- Consistent and reproducible test environment
- No external dependencies or complex infrastructure

#### Option 2: Using Rancher Desktop

If you need to test against a real Kubernetes implementation, [Rancher Desktop](https://rancherdesktop.io/) provides a convenient way to run Kubernetes locally:

1. **Enable Kubernetes in Rancher Desktop**:
   - Open Rancher Desktop
   - Go to Preferences → Kubernetes
   - Ensure Kubernetes is enabled and running

2. **Configure Environment Variables**:

bash # Required: Tell tests to use your existing cluster instead of KWOK export K8SMCPTESTUSEEXISTING_CLUSTER=true

# Optional: Specify Rancher Desktop context export K8S_CONTEXT=rancher-desktop

# Optional: Skip cleanup of test namespaces export K8SSKIPCLEANUP=true

3. **Run Integration Tests**:

bash pytest tests/integration -v

#### Option 3: Using Another Existing Kubernetes Cluster

For testing against production-like environments or specific Kubernetes distributions:

bash

Set required environment variables

export K8SMCPTESTUSEEXISTING_CLUSTER=true

Optionally specify a context

export K8S_CONTEXT=my-cluster-context

Run the tests

pytest -m integration

This approach works with any Kubernetes distribution (EKS, GKE, AKS, k3s, k0s, etc.).

#### Option 4: Setting Up a Local Kubernetes Cluster for Development

For local development, we recommend setting up a lightweight Kubernetes cluster:

**Using k3s (Recommended for Linux):**

[k3s](https://k3s.io/) is a certified lightweight Kubernetes distribution:

bash

Install k3s

curl -sfL https://get.k3s.io | sh -

Get kubeconfig (sudo is required to read the config)

sudo cat /etc/rancher/k3s/k3s.yaml > ~/.kube/k3s-config

Fix permissions

chmod 600 ~/.kube/k3s-config

Set KUBECONFIG to use this file

export KUBECONFIG=~/.kube/k3s-config

Verify it's running

kubectl get nodes

**Using k0s (Recommended for all platforms):**

[k0s](https://k0sproject.io/) is a zero-friction Kubernetes distribution:

bash

Install k0s

curl -sSLf https://get.k0s.sh | sh

Create a single-node cluster

sudo k0s install controller --single sudo k0s start

Get kubeconfig

sudo k0s kubeconfig admin > ~/.kube/k0s-config chmod 600 ~/.kube/k0s-config export KUBECONFIG=~/.kube/k0s-config

Verify it's running

kubectl get nodes

**Using Minikube:**

[Minikube](https://minikube.sigs.k8s.io/docs/start/) creates a local Kubernetes cluster within a VM or container:

bash

Install Minikube

macOS with Homebrew:

brew install minikube

Start a cluster

minikube start

Verify it's running

kubectl get nodes

**Using Kind (Kubernetes in Docker):**

[Kind](https://kind.sigs.k8s.io/docs/user/quick-start/) runs Kubernetes clusters using Docker containers as nodes:

bash

Install Kind

macOS with Homebrew:

brew install kind

Create a cluster

kind create cluster --name k8s-mcp-test

Verify it's running

kubectl get nodes

**Using K3d (Lightweight Kubernetes):**

[K3d](https://k3d.io/) is a lightweight wrapper to run [k3s](https://k3s.io/) in Docker:

bash

Install K3d

macOS with Homebrew:

brew install k3d

Create a cluster

k3d cluster create k8s-mcp-test

Verify it's running

kubectl get nodes

#### Environment Variables for Integration Tests

You can customize the integration tests with these environment variables:

| Environment Variable | Description | Default |
|----------------------|-------------|---------|
| `K8S_MCP_TEST_USE_KWOK` | Use KWOK to create a test cluster | `true` |
| `K8S_MCP_TEST_USE_EXISTING_CLUSTER` | Use existing cluster instead of creating a new one | `false` |
| `K8S_CONTEXT` | Kubernetes context to use for tests | *current context* |
| `K8S_SKIP_CLEANUP` | Skip cleanup of test resources | `false` |

Example usage:

bash

Force using KWOK even if other variables are set

export K8SMCPTESTUSEKWOK=true pytest -m integration

Use existing cluster with a specific context

export K8SMCPTESTUSEEXISTINGCLUSTER=true export K8SCONTEXT=my-dev-cluster pytest -m integration

Skip cleanup of test resources (useful for debugging)

export K8SSKIPCLEANUP=true pytest -m integration

#### Continuous Integration with GitHub Actions

The project includes GitHub Actions workflows that automatically run integration tests:

1. **CI Workflow**: Runs unit tests on every PR to ensure code quality
2. **Integration Tests Workflow**: Sets up a KWOK cluster and runs integration tests against it

The integration test workflow:
- Installs KWOK on the CI runner
- Creates a lightweight simulated Kubernetes cluster
- Installs all required CLI tools (kubectl, helm, istioctl, argocd)
- Runs all tests marked with the 'integration' marker
- Cleans up the KWOK cluster when done

You can also manually trigger the integration tests from the GitHub Actions tab, with an option to enable debugging if needed.

#### Why KWOK for Testing?

KWOK (Kubernetes Without Kubelet) provides significant advantages for testing Kubernetes command execution:

1. **Lightweight and Fast**: KWOK clusters start in seconds without requiring container runtime
2. **Focus on API Interaction**: Perfect for testing Kubernetes CLI commands and API responses
3. **Consistent Environment**: Provides deterministic responses for predictable testing
4. **Resource Efficiency**: Eliminates the overhead of running actual containers or nodes
5. **CI/CD Friendly**: Ideal for continuous integration pipelines with minimal resource requirements

Since our integration tests primarily validate command formation, execution, and output parsing rather than actual workload behavior, KWOK provides an ideal balance of fidelity and efficiency.

## Security Considerations

The server includes several safety features:

- **Isolation**: When running in Docker, the server operates in an isolated container environment
- **Read-only access**: Mount Kubernetes configuration as read-only (`-v ~/.kube:/home/appuser/.kube:ro`)
- **Non-root execution**: All processes run as a non-root user inside the container
- **Command validation**: Potentially dangerous commands require explicit resource names
- **Context separation**: Automatic context and namespace injection for commands

### Security Modes and Configuration

K8s MCP Server supports two security modes and customizable security rules:

- **Strict Mode** (default): All commands are validated against security rules
- **Permissive Mode**: Security validation is skipped, allowing all commands to execute

#### Setting Security Mode

To run in permissive mode (allow all commands):

json { "mcpServers": { "k8s-mcp-server": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "~/.kube:/home/appuser/.kube:ro", "-e", "K8SMCPSECURITY_MODE=permissive", "ghcr.io/alexei-led/k8s-mcp-server:latest" ] } } }

#### Customizing Security Rules

Security rules can be customized using a YAML configuration file. This allows for more flexibility than the built-in rules.

1. **Create a Security Configuration File**:
   Create a YAML file with your custom rules (e.g., `security_config.yaml`):

yaml # Security configuration for k8s-mcp-server

# Potentially dangerous command patterns (prefix-based) dangerous_commands: kubectl: - "kubectl delete" - "kubectl drain" # Add your custom dangerous commands here

# Safe pattern overrides (prefix-based) safe_patterns: kubectl: - "kubectl delete pod" - "kubectl delete deployment" # Add your custom safe patterns here

# Advanced regex pattern rules regexrules: kubectl: - pattern: "kubectl\s+delete\s+(-[A-Za-z]+\s+)*--all\b" description: "Deleting all resources of a type" errormessage: "Deleting all resources is restricted. Specify individual resources to delete." # Add your custom regex rules here

2. **Mount the Configuration File in Docker**:

json { "mcpServers": { "k8s-mcp-server": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "~/.kube:/home/appuser/.kube:ro", "-v", "/path/to/securityconfig.yaml:/securityconfig.yaml:ro", "-e", "K8SMCPSECURITYCONFIG=/securityconfig.yaml", "ghcr.io/alexei-led/k8s-mcp-server:latest" ] } } }

#### Configuration Structure

The security configuration YAML file has three main sections:

1. **dangerous_commands**: Dictionary of command prefixes that are considered dangerous for each tool
2. **safe_patterns**: Dictionary of command prefixes that override dangerous commands (exceptions)
3. **regex_rules**: Advanced regex patterns for more complex validation rules

Each regex rule should include:
- **pattern**: Regular expression pattern to match against commands
- **description**: Description of what the rule checks for
- **error_message**: Custom error message to display when the rule is violated

#### Examples

**Example 1: Restricting Namespace Operations**

yaml regexrules: kubectl: - pattern: "kubectl\s+.*\s+--namespace=kube-system\b" description: "Operations in kube-system namespace" errormessage: "Operations in kube-system namespace are restricted."

**Example 2: Allowing Additional Safe Patterns**

yaml safe_patterns: kubectl: - "kubectl delete pod" - "kubectl delete job" - "kubectl delete cronjob"

**Example 3: Restricting Dangerous File System Access**

yaml regexrules: kubectl: - pattern: "kubectl\s+exec\s+.\s+-[^-]c\s+.*(rm|mv|cp|curl|wget|chmod)\b" description: "Dangerous file operations in exec" errormessage: "File system operations within kubectl exec are restricted."

## Project Architecture and Code Structure

K8s MCP Server is organized around a modular architecture that separates concerns and promotes maintainability:

mermaid flowchart TD A[main.py] --> B[server.py] B --> C[config.py] B --> D[cliexecutor.py] B --> E[prompts.py] D --> F[security.py] D --> G[tools.py] D --> H[errors.py] B --> I[loggingutils.py]

classDef core fill:#f9f,stroke:#333,stroke-width:2px
classDef utils fill:#bbf,stroke:#333,stroke-width:1px

class A,B,D core
class C,E,F,G,H,I utils

### Key Components:

1. **server.py**: The central component that initializes the MCP server, registers tools and prompts, and manages client connections. It implements the Model Context Protocol and handles request/response lifecycle.

2. **cli_executor.py**: Manages the execution of CLI commands with proper validation, timeout handling, and error capture. It translates between the abstract tool requests and the concrete CLI commands.

3. **security.py**: Implements command validation rules and security checks to prevent potentially dangerous operations. It enforces restrictions on allowed commands and parameters.

4. **tools.py**: Defines common utilities, data structures, and helper functions for working with Kubernetes commands.

5. **prompts.py**: Registers and defines template prompts for common Kubernetes operations to improve AI interactions.

6. **config.py**: Manages configuration settings for the server, including environment variables, default values, and supported CLI tools.

7. **errors.py**: Provides standardized error handling, custom exceptions, and error formatting.

8. **logging_utils.py**: Implements consistent logging infrastructure across the application.

### Design Principles:

- **Separation of Concerns**: Each module has a well-defined responsibility and role.
- **Centralized Configuration**: Settings are managed through a single configuration module.
- **Standardized Error Handling**: Consistent error treatment across all components.
- **Extensibility**: The architecture makes it easy to add support for new Kubernetes CLI tools.
- **Security First**: Security validation is integrated throughout the command lifecycle.
- **Fault Tolerance**: Robust error handling and recovery mechanisms.

This architecture allows for flexibility while maintaining simplicity, with clear interfaces between components and well-defined responsibilities.

## For Contributors

If you're interested in contributing to K8s MCP Server, here's an overview of the project structure:

### Project Structure

k8s-mcp-server/ ├── src/ │ └── k8smcpserver/ │ ├── server.py # MCP server initialization and tool registration │ ├── cliexecutor.py # Command execution and process management │ ├── security.py # Command validation and security rules │ ├── tools.py # Shared utilities and data structures │ ├── errors.py # Standardized error handling │ ├── prompts.py # Prompt templates for common operations │ ├── config.py # Configuration and settings │ └── loggingutils.py # Logging infrastructure ├── tests/ │ ├── unit/ # Unit tests (no K8s cluster required) │ └── integration/ # Integration tests (requires K8s cluster or KWOK) └── deploy/ └── docker/ # Docker deployment configuration

### Development Workflow

1. **Setup Development Environment**:

bash git clone https://github.com/alexei-led/k8s-mcp-server.git cd k8s-mcp-server uv venv -p 3.13 source .venv/bin/activate uv pip install -e ".[dev]"

2. **Run Tests**:

bash # Unit tests pytest -m unit

# Integration tests (using KWOK) pytest -m integration

3. **Submit Pull Requests**:
   - Fork the repository
   - Create your feature branch (`git checkout -b feature/amazing-feature`)
   - Commit your changes (`git commit -m 'Add some amazing feature'`)
   - Push to the branch (`git push origin feature/amazing-feature`)
   - Open a Pull Request

### Contribution Guidelines

- **Code Style**: Follow PEP 8 and the project's style guide (enforced via `ruff`)
- **Documentation**: Keep code comments and documentation up-to-date with changes
- **Testing**: Add tests for new functionality with good coverage
- **Simplicity**: Favor simple, maintainable solutions over complex ones
- **Security**: Keep security as a primary consideration in all changes
- **Dependencies**: Add new dependencies only when they provide significant value

### Development and Debugging

K8s MCP Server is built using the [Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk). Here are some tips for developing and debugging:

#### Using MCP Inspector

The MCP Inspector is a powerful tool for local development and testing:

bash

Install the MCP CLI if not already installed

pip install "mcp[cli]"

Run the server with the inspector

mcp dev src/k8smcpserver/server.py

The inspector provides:
- Interactive testing of tools and prompts
- Visualization of request/response flows
- Direct execution of commands without Claude Desktop

#### Local Development Without Docker

For quick iteration during development:

bash

Set up a development environment

uv venv -p 3.13 source .venv/bin/activate uv pip install -e ".[dev]"

Run the server directly

python -m k8smcpserver

Or use the MCP run command

mcp run src/k8smcpserver/server.py

#### Debugging Tips

1. **Enable Debug Logging**:

bash export LOGLEVEL=DEBUG python -m k8smcpserver

2. **Test Individual Tools**:
   Use the MCP Inspector to test specific tools in isolation before integrating with Claude.

3. **Inspect MCP Protocol**:
   Monitor the raw MCP protocol messages using the inspector to understand how Claude interacts with your server.

4. **Local Testing with Claude Desktop**:
   During development, you can point Claude Desktop to your local server instead of using Docker:

json { "mcpServers": { "k8s-mcp-server": { "command": "docker", "args": [ "run", "-i", "--rm", "--network=host", "-v", "/Users/YOURUSERNAME/.kube:/home/appuser/.kube", "ghcr.io/alexei-led/k8s-mcp-server:latest" ] } } } ```

Development Best Practices

• Modular Design: Create reusable, single-purpose components
• Error Handling: Implement robust error handling with helpful messages
• Logging: Use appropriate logging levels (debug, info, error)
• Security: Follow input validation and safe execution practices
• Testing: Write comprehensive unit and integration tests
• Documentation: Document complex logic and architectural decisions
• Backward Compatibility: Maintain compatibility with existing clients when possible

License

This project is licensed under the MIT License - see the LICENSE file for details.