---
title: "Kyverno MCP Server"
description: "Model Context Protocol server for Kyverno"
diataxis: how-to
applies_to:
  product: "kyverno"
audience: ["platform-engineer","devsecops"]
last_updated: 2026-03-25
url: https://docs.nirmata.io/docs/controllers/n4k/kyverno-mcp/
---


## Overview

The Kyverno MCP Server is a Model Context Protocol (MCP) server that provides Kyverno policy management capabilities through a standardized interface. This server enables AI assistants to interact with Kyverno policies in Kubernetes clusters, making policy management more accessible and automated.

Whether you're looking to proactively assess the security posture of your clusters before implementing Kyverno, or you need to monitor and analyze policy violations in existing Kyverno deployments, the MCP server provides the tools and guidance necessary for comprehensive policy management across your Kubernetes infrastructure.

## What is MCP?

Model Context Protocol (MCP) is a standardized protocol that allows AI assistants to interact with external tools and services. The Kyverno MCP Server implements this protocol to expose Kyverno's policy management capabilities to AI-powered tools like Claude Desktop, Amazon Q, Cursor, and other MCP-compatible clients.

## Key Features

- **Proactive Policy Scanning**: Test cluster resources against curated Kyverno policy sets, Git repositories, or local policies to discover security issues without requiring Kyverno installation
- **Real-time Violation Monitoring**: View detailed policy violations and compliance status from PolicyReport and ClusterPolicyReport custom resources in clusters with deployed policies
- **Multi-Cluster Management**: Seamlessly switch between Kubernetes contexts to scan or monitor policies across different environments
- **AI-Powered Guidance**: Natural language interaction with built-in help system for Kyverno installation and troubleshooting
- **Flexible Deployment Options**: Run as a local binary, container, or expose via HTTP(S) for different integration scenarios

## Quick Links

### Getting Started
- [Installation Guide](./installation/) - Detailed installation instructions
- [Quick Start](./getting-started/) - Get up and running in minutes
- [Use Cases & Scenarios](./usage/) - Real-world scenarios and user stories
- [Available Tools](./available-tools/) - Complete tool reference

### Configuration & Usage
- [Configuration Options](./configuration/) - All configuration settings

### Support & Resources
- [Troubleshooting](./troubleshooting/) - Common issues and solutions
- [GitHub Repository](https://github.com/nirmata/kyverno-mcp) - Source code and contributions

## Prerequisites

- Go 1.24 or higher (for building from source)
- Access to a Kubernetes cluster with a valid kubeconfig
- Kyverno installed in your cluster (for violation monitoring; optional for proactive policy assessment)

## Installation Options

### Quick Install with Homebrew

```bash
brew tap nirmata/tap
brew install kyverno-mcp
```text

### Download Pre-built Binaries

Download the appropriate binary for your platform from the [Nirmata downloads page](https://downloads.nirmata.io/kyverno-mcp/downloads/).

### Run with Docker

```bash
# Build the image
docker build -t kyverno-mcp:latest .

# Run with mounted kubeconfig
docker run --rm -i \
  -v $HOME/.kube/config:/kube/config:ro \
  kyverno-mcp:latest -- \
  --kubeconfig /kube/config
```text

For detailed installation instructions, see the [Installation Guide](./installation/).

## Getting Started

### Basic Usage

Start the server using your default kubeconfig:

```bash
./kyverno-mcp
```json

Or specify a custom kubeconfig:

```bash
./kyverno-mcp --kubeconfig=/path/to/kubeconfig
```json

### Configure Your MCP Client

Add the Kyverno MCP server to your MCP client configuration:

```json
{
  "mcpServers": {
    "kyverno": {
      "command": "/path/to/kyverno-mcp",
      "args": [
        "--kubeconfig=/path/to/your/kubeconfig"
      ]
    }
  }
}
```text

For a complete getting started tutorial, see the [Getting Started Guide](./getting-started/).

### Network Access (HTTP/HTTPS)

For remote access or browser-based clients, expose the server over HTTP(S):

```bash
# HTTPS (recommended for production)
./kyverno-mcp \
  --http-addr :8443 \
  --tls-cert /path/to/cert.pem \
  --tls-key /path/to/key.pem

# HTTP (local testing only)
./kyverno-mcp --http-addr :8080
```text

⚠️ **Security Note**: Never expose the server over plain HTTP in production. Always use HTTPS with valid TLS certificates or place the server behind an HTTPS-terminating proxy.

## Available Tools

The Kyverno MCP Server provides the following tools:

### Context Management

- **`list_contexts`**: List all available Kubernetes contexts
- **`switch_context`**: Switch to a different Kubernetes context

### Policy Operations

- **`apply_policies`**: Scan cluster resources against Kyverno policies from curated sets, Git repos, or local files
  - Supports policy sets: `pod-security`, `rbac-best-practices`, `kubernetes-best-practices`, `all`
  - Enable proactive security assessment by testing policies without requiring Kyverno installation
  - Source policies from Git repositories or local filesystem paths for custom policy testing
  - Provides immediate, non-persistent violation reports using `kyverno apply`

### Monitoring & Compliance

- **`show_violations`**: Read and display policy violations from PolicyReport and ClusterPolicyReport custom resources
  - Shows both namespaced and cluster-wide violations with severity levels and timestamps
  - Provides detailed violation analysis including affected resources and policy details
  - Requires Kyverno installation and deployed policies to function
  - Offers Kyverno installation guidance when not yet deployed

### Documentation

- **`help`**: Access built-in Kyverno documentation
  - Topics: `installation`, `troubleshooting`

For detailed tool documentation, see the [Available Tools Reference](./available-tools/).

## Command Line Reference

| Flag | Description | Default |
|------|-------------|---------|
| `--kubeconfig` | Path to kubeconfig file | `$KUBECONFIG` or `~/.kube/config` |
| `--http-addr` | HTTP(S) server bind address | None (stdio mode) |
| `--tls-cert` | TLS certificate file path | None |
| `--tls-key` | TLS private key file path | None |

For complete configuration options, see the [Configuration Guide](./configuration/).

## Use Cases

### Proactive Security Assessment
Scan clusters for policy violations without installing Kyverno:

**Scenario**: *As a DevOps engineer, I want to scan my Kubernetes clusters for policy violations and assess their security posture without needing to install Kyverno or deploy policies to the cluster.*

- Scan existing cluster resources against curated policy sets
- Get immediate, non-persistent violation reports
- Receive guidance on Kyverno installation and policy deployment
- Establish baseline security requirements across multiple environments

```text
Apply pod security policies to my cluster and show me what violations occur
```

### Compliance Monitoring & Violation Analysis
Monitor ongoing compliance in clusters with deployed Kyverno policies:

**Scenario**: *As a security engineer, I want to monitor compliance across my Kubernetes clusters that already have Kyverno installed and policies deployed, and get detailed reports on policy violations from PolicyReport resources.*

- Real-time violation monitoring from PolicyReport custom resources
- Detailed analysis with severity levels, affected resources, and timestamps
- Filtered reporting by namespace, policy type, or severity
- Current state monitoring of policy violations

```text
Show me all high-severity violations in the production namespace
```

### Multi-Cluster Policy Management
Manage policies consistently across development, staging, and production:
```text
Compare policy violations between staging and production clusters
```

### Automated Policy Testing
Test security policies across multiple clusters with AI assistance:
```text
Apply rbac-best-practices to all my clusters and show me the compliance status
```

## Next Steps

- [Install Kyverno](https://kyverno.io/docs/installation/) in your cluster
- Explore [Kyverno policies](https://kyverno.io/policies/)
- Learn about [Model Context Protocol](https://modelcontextprotocol.io/)
- Join the [Kyverno community](https://kyverno.io/community/)

## Support

- **Documentation**: Full documentation available in this guide
- **GitHub Issues**: [Report bugs or request features](https://github.com/nirmata/kyverno-mcp/issues)
- **Community**: Join the [Kyverno Slack channel](https://kubernetes.slack.com/archives/CLGR9BJU9)

## Quick Start

Ready to get started? Check out our guides:

- **[Getting Started](getting-started)** - Quick setup guide
- **[Usage](usage)** - Real-world scenarios and user stories
- **[Installation](installation)** - Detailed installation instructions
- **[Available Tools](available-tools)** - Complete tool reference
- **[Configuration](configuration)** - Configuration options
## Documentation

- **[Troubleshooting](troubleshooting)** - Common issues and solutions

Visit our [GitHub repository](https://github.com/nirmata/kyverno-mcp) for source code and development information.


---

## Getting Started


## Quick Start

This guide will help you get started with Kyverno MCP in minutes.

### Prerequisites

Before you begin, ensure you have:
- Access to a Kubernetes cluster
- A valid kubeconfig file
- Kyverno installed in your cluster (optional, but recommended)

### Step 1: Install Kyverno MCP

Choose your preferred installation method:

#### Using Homebrew (macOS/Linux)
```bash
brew tap nirmata/tap
brew install kyverno-mcp
```json

#### Download Binary
Download the appropriate binary for your platform from the [Nirmata downloads page](https://downloads.nirmata.io/kyverno-mcp/downloads/).

### Step 2: Configure Your MCP Client

Add Kyverno MCP to your MCP client configuration. For example, in Claude Desktop:

1. Open your Claude Desktop configuration file:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. Add the Kyverno MCP server:
```json
{
  "mcpServers": {
    "kyverno": {
      "command": "/path/to/kyverno-mcp",
      "args": [
        "--kubeconfig=/path/to/your/kubeconfig"
      ]
    }
  }
}
```

### Step 3: Test the Connection

1. Start your MCP client (e.g., Claude Desktop)
2. Ask about your Kubernetes contexts:
```text
3. The assistant should be able to list your contexts using the `list_contexts` tool

### Step 4: Apply Your First Policy

Try scanning your cluster with recommended policy sets for pod security, RBAC and Kubernetes best practices:

```text
Scan my cluster for policy violations
```

The assistant will use the `apply_policies` tool to apply curated pod security policies.

### Step 5: Check for Violations

Monitor policy violations:

```text
Show me any policy violations in my cluster
```

The assistant will use the `show_violations` tool to display any policy violations.

## What's Next?

- Explore [usage](usage.md) for detailed real-world examples
- Learn about [available tools and commands](available-tools.md)
- Explore [advanced configuration options](configuration.md)
- Check out [troubleshooting tips](troubleshooting.md) 

---

## Usage


## Overview

Kyverno MCP serves two primary use cases that address different stages of the Kubernetes policy management lifecycle. Whether you're proactively assessing cluster security or monitoring existing policy deployments, these scenarios demonstrate how to leverage Kyverno MCP effectively.

## Scenario 1: Proactive Assessment

In this scenario, Kyverno is not installed on your clusters. You can use the Kyverno MCP server to scan cluster resources with recommended or custom policy sets.

### The Challenge

*"As a DevOps engineer, I want to scan my Kubernetes clusters for policy violations and assess their security posture without needing to install Kyverno or deploy policies to the cluster."*

Organizations often need to:
- Evaluate security risks in existing clusters
- Understand policy implications before deployment
- Establish baseline security requirements
- Get guidance on Kyverno installation and configuration

### How Kyverno MCP Helps

#### 1. **Policy Scanning and Assessment**
Test cluster resources against curated policy sets to discover potential security issues:

```text
Apply pod security policies to my development cluster
```text

This command will:
- Scan existing cluster resources against security policies using `kyverno apply`
- Identify resources that would violate the [Kubernetes Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/)
- Provide immediate, non-persistent violation reports to stdout
- Work without requiring Kyverno to be installed in the cluster

#### 2. **Multi-Environment Evaluation**
Scan security posture across different environments:

```text
Switch to staging-cluster and scan my cluster for default policies violations
```text

#### 3. **Installation Guidance**
Get contextual guidance for Kyverno deployment:

```text
Show me how to install Kyverno in my cluster
```text

### Benefits
- **Risk-free scanning**: Test policies against existing resources without affecting running workloads
- **No infrastructure changes**: Scan clusters without installing Kyverno or deploying policies
- **Informed decisions**: Understand policy impact before committing to actual deployment
- **Guided implementation**: Get step-by-step installation guidance for full policy enforcement
- **Baseline establishment**: Create security standards across environments

### Example Workflow

1. **Initial Assessment**
   ```
   List my available Kubernetes contexts
   ```

2. **Environment Selection**
   ```
   Switch to development-cluster
   ```

3. **Policy Scanning and Impact Analysis**
   ```
   Scan my cluster for default policies violations
   ```

4. **Implementation Planning**
   ```
   Show me how to install Kyverno and deploy policies for enforcement
   ```

### Moving from Scanning to Enforcement

After using the MCP tool to scan your cluster and understand policy violations, actual policy deployment requires:

1. **Install Kyverno** in your cluster (using [Kyverno Installation](https://kyverno.io/docs/installation/))
2. **Deploy policies** using standard Kubectl apply command ([kubectl apply](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_apply/))
3. **Monitor violations** using the `show_violations` tool to read PolicyReport custom resources ([PolicyReport](https://kyverno.io/docs/policy-reports/))

>NOTE: The MCP tool provides scanning capabilities but does not deploy policies to your cluster. Policy deployment is handled through standard Kubernetes deployment methods.

## Scenario 2: Compliance Monitoring & Violation Analysis

In this scenario, Kyverno is installed on your clusters, along with one or more policy sets. You can use the Kyverno MCP server to manage policy violations.

### The Challenge

*"As a security engineer, I want to monitor compliance across my Kubernetes clusters that already have Kyverno installed and policies deployed, and get current violation reports from PolicyReport resources."*

Security teams need to:
- Monitor ongoing policy compliance
- Quickly identify and prioritize violations
- Generate compliance reports
- View current security posture

### Prerequisites for This Scenario
- Kyverno installed in the cluster
- Policies deployed using `kubectl apply -f <policy.yaml>`
- PolicyReport custom resources being generated by deployed policies

### How Kyverno MCP Helps

#### 1. **Current Violation Monitoring**
Read PolicyReport custom resources to get visibility into active policy violations:

```text
Show me all policy violations in the production namespace
```

This provides:
- **Detailed violation information**: Policy name, affected resource, severity level from PolicyReport CRs
- **Contextual data**: Namespace, timestamps, and descriptive messages
- **Prioritized results**: Violations grouped by severity (high, medium, low)
- **Current state snapshot**: Shows violations as they exist now in the cluster

**Note**: The tool provides current violation snapshots only. It does not:
- Track historical violation trends over time
- Show which policy set (e.g., kubernetes-best-practices) violations belong to
- Provide aggregation by namespace or other dimensions
- Access PolicyReport creation metadata

#### 2. **Filtered Analysis**
Focus on specific areas of concern:

```text
Show me high-severity violations in the production namespace
```

#### 3. **Multi-Cluster Compliance**
Monitor compliance across multiple environments:

```text
Compare policy violations between staging and production clusters
```

### Benefits
- **Immediate visibility**: Real-time access to current violation data
- **Actionable insights**: Detailed information for remediation
- **Current state monitoring**: View existing policy violations
- **Efficient prioritization**: Focus on high-impact violations first

### Example Workflow

1. **Daily Compliance Check**
   ```
   Show me all policy violations in the cluster
   ```

2. **Priority Assessment**
   ```
   Show me all high-severity violations
   ```

3. **Namespace-Specific Analysis**
   ```
   Show policy violations in the production namespace
   ```

4. **Cross-Environment Comparison**
   ```
   Switch to staging-cluster and show me policy violations
   ```

5. **Policy-Specific Violations**
   ```
   Show me violations for the require-resource-limits policy
   ```

### Sample Violation Report

```json
{
  "violations": [
    {
      "policy": "disallow-privileged-containers",
      "resource": "pod/webapp-xyz",
      "namespace": "production",
      "severity": "high",
      "message": "Privileged containers are not allowed",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "policy": "require-resource-limits",
      "resource": "deployment/backend",
      "namespace": "staging",
      "severity": "medium",
      "message": "Container 'api' does not have resource limits set"
    }
  ],
  "summary": {
    "total": 2,
    "high": 1,
    "medium": 1,
    "low": 0
  }
}
```

## Advanced Scenarios

### Multi-Cluster Security Governance

**Scenario**: Managing security policies across development, staging, and production environments.

```text


### Policy Impact Assessment

**Scenario**: Understanding the impact of new policies before enforcement.

```text

## Best Practices

### 1. **Start with Assessment**
Always begin with a security assessment before applying policies:
```text
Show me existing policy violations in my cluster
```

### 2. **Test Policy Impact**
Test policies to understand their impact on existing resources:
```text
Apply pod security policies to explain their impact
```

### 3. **Context Awareness**
Always verify the current context:
```text

## Integration with Existing Workflows

### DevOps Integration
- **Pre-deployment checks**: Assess security before new deployments
- **Policy validation**: Test policies in development environments
- **Compliance gates**: Integrate with CI/CD pipelines

### Security Operations
- **Daily monitoring**: Regular violation checks
- **Incident response**: Quick identification of security issues
- **Audit preparation**: Generate compliance reports

### Platform Engineering
- **Cluster standardization**: Consistent security policies across environments
- **Developer guidance**: Provide security best practices
- **Policy evolution**: Continuous improvement of security posture

## Next Steps

- Learn about [Available Tools](available-tools.md) for detailed tool documentation
- Explore [Configuration Options](configuration.md) for advanced setup
- Review [Security Best Practices](#best-practices) for production deployment
- Check [Troubleshooting Guide](troubleshooting.md) for common issues


---

## Installation


## Installation Methods

Kyverno MCP can be installed using several methods depending on your operating system and preferences.

### Prerequisites

- Go 1.24 or higher (only for building from source)
- Access to a Kubernetes cluster with a valid kubeconfig
- Kyverno installed in your cluster (for policy operations)

### Option 1: Homebrew (Recommended for macOS/Linux)

The easiest way to install Kyverno MCP on macOS or Linux:

```bash
# Add the Nirmata tap
brew tap nirmata/tap

# Install Kyverno MCP
brew install kyverno-mcp

# Verify installation
kyverno-mcp --version
```

### Option 2: Pre-built Binaries

Download pre-built binaries for your platform:

1. Visit the [Nirmata downloads page](https://downloads.nirmata.io/kyverno-mcp/downloads/)
2. Download the appropriate binary for your platform:
   - `kyverno-mcp-darwin-amd64` for macOS (Intel)
   - `kyverno-mcp-darwin-arm64` for macOS (Apple Silicon)
   - `kyverno-mcp-linux-amd64` for Linux (x86_64)
   - `kyverno-mcp-windows-amd64.exe` for Windows

3. Make the binary executable (macOS/Linux):
```bash
chmod +x kyverno-mcp-*
```

4. Move to a directory in your PATH:
```bash
sudo mv kyverno-mcp-* /usr/local/bin/kyverno-mcp
```

### Option 3: Build from Source

If you prefer to build from source:

```bash
# Clone the repository
git clone https://github.com/nirmata/kyverno-mcp.git
cd kyverno-mcp

# Build the binary
go build -o kyverno-mcp ./cmd/kyverno-mcp

# Install to PATH
sudo mv kyverno-mcp /usr/local/bin/
```

### Option 4: Docker

Run Kyverno MCP using Docker:

```bash
# Build the Docker image
docker build -t kyverno-mcp:latest .

# Run with mounted kubeconfig
docker run --rm -i \
  -v $HOME/.kube/config:/kube/config:ro \
  kyverno-mcp:latest -- \
  --kubeconfig /kube/config
```

For Docker Compose:

```yaml
version: '3.8'
services:
  kyverno-mcp:
    image: kyverno-mcp:latest
    volumes:
      - ${HOME}/.kube/config:/kube/config:ro
    environment:
      - KUBECONFIG=/kube/config
    stdin_open: true
    tty: true
```

## Verifying Installation

After installation, verify that Kyverno MCP is working correctly:

```bash
# Check version
kyverno-mcp --version

# Test with default kubeconfig
kyverno-mcp

# Test with specific kubeconfig
kyverno-mcp --kubeconfig=/path/to/kubeconfig
```

## Platform-Specific Notes

### macOS
- If using Homebrew, updates are handled via `brew upgrade kyverno-mcp`
- For Apple Silicon Macs, ensure you download the `arm64` binary

### Linux
- Add the binary location to your `$PATH` in `~/.bashrc` or `~/.zshrc`
- Consider creating a systemd service for HTTP mode

### Windows
- Add the executable location to your system PATH
- Use PowerShell or Command Prompt to run the tool
- Consider using Windows Subsystem for Linux (WSL) for better compatibility

## Troubleshooting Installation

### Permission Denied
If you get a "permission denied" error:
```bash
chmod +x kyverno-mcp
```

### Command Not Found
If the command is not found after installation:
1. Check if the binary is in your PATH: `echo $PATH`
2. Add the directory to PATH: `export PATH=$PATH:/path/to/directory`

### Kubeconfig Issues
If you encounter kubeconfig errors:
1. Verify your kubeconfig exists: `ls ~/.kube/config`
2. Test kubectl access: `kubectl cluster-info`
3. Specify kubeconfig explicitly: `kyverno-mcp --kubeconfig=/path/to/config`

## Next Steps

- Continue with the [Getting Started](getting-started.md) guide
- Learn about [Configuration Options](configuration.md)
- Explore [Available Tools](available-tools.md) 

---

## Available Tools


## Overview

Kyverno MCP provides several tools that AI assistants can use to interact with Kyverno and Kubernetes. Each tool is designed for specific operations and returns structured data.

## Context Management Tools

### list_contexts

Lists all available Kubernetes contexts from your kubeconfig.

**Purpose**: Discover available Kubernetes clusters/contexts

**Example Request**:
```text
List all my available Kubernetes contexts
```text

**Example Response**:
```json
{
  "contexts": [
    {
      "name": "production-cluster",
      "cluster": "prod-k8s",
      "user": "admin@prod"
    },
    {
      "name": "staging-cluster",
      "cluster": "staging-k8s",
      "user": "admin@staging"
    }
  ],
  "current": "production-cluster"
}
```json

### switch_context

Switches to a different Kubernetes context.

**Purpose**: Change the active Kubernetes cluster

**Parameters**:
- `context`: The name of the context to switch to

**Example Request**:
```text
Switch to the staging-cluster context
```text

**Example Response**:
```json
{
  "message": "Switched to context: staging-cluster",
  "previous": "production-cluster",
  "current": "staging-cluster"
}
```json

## Policy Management Tools

### apply_policies

Applies Kyverno policies from various sources.

**Purpose**: Deploy policies to enforce security and compliance

**Parameters**:
- `source`: The source of policies
  - Curated sets: `pod-security`, `rbac-best-practices`, `kubernetes-best-practices`, `all`
  - Git repository: `https://github.com/org/repo`
  - Local path: `/path/to/policies`
- `namespace`: (Optional) Target namespace for policies

**Example Requests**:

1. Apply curated pod security policies:
```text
Apply pod security policies to my cluster
```text

2. Apply policies from a Git repository:
```text
Apply policies from https://github.com/myorg/kyverno-policies
```text

3. Apply all curated policies:
```text
Apply all best practice policies to the cluster
```text

**Example Response**:
```json
{
  "message": "Successfully applied 15 policies",
  "policies": [
    "disallow-privileged-containers",
    "require-run-as-non-root",
    "restrict-volume-types"
  ],
  "source": "pod-security"
}
```json

## Monitoring Tools

### show_violations

Displays policy violations from PolicyReport and ClusterPolicyReport resources.

**Purpose**: Monitor compliance and identify issues

**Parameters**:
- `namespace`: (Optional) Filter violations by namespace
- `severity`: (Optional) Filter by severity level

**Example Requests**:

1. Show all violations:
```text
Show me all policy violations in the cluster
```text

2. Show violations in a specific namespace:
```text
Show policy violations in the production namespace
```text

**Example Response**:
```json
{
  "violations": [
    {
      "policy": "disallow-privileged-containers",
      "resource": "pod/webapp-xyz",
      "namespace": "production",
      "severity": "high",
      "message": "Privileged containers are not allowed",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "policy": "require-resource-limits",
      "resource": "deployment/backend",
      "namespace": "staging",
      "severity": "medium",
      "message": "Container 'api' does not have resource limits set"
    }
  ],
  "summary": {
    "total": 2,
    "high": 1,
    "medium": 1,
    "low": 0
  }
}
```json

**What this tool provides**:
- Current violation snapshots from PolicyReport CRs
- Individual violation details (policy, resource, namespace, severity, message)
- Basic timestamps for when violations occurred
- Summary counts by severity level

**What this tool does NOT provide**:
- Historical violation data or trends over time
- Policy set categorization (e.g., which violations belong to "kubernetes-best-practices")
- Aggregation capabilities (e.g., violation counts by namespace)
- PolicyReport metadata (creation times, report metadata)
- Trend analysis or time-based patterns

**Note**: If Kyverno is not installed, this tool will provide installation instructions.

## Documentation Tool

### help

Provides built-in documentation and guidance.

**Purpose**: Access Kyverno documentation and troubleshooting help

**Parameters**:
- `topic`: The help topic
  - `installation`: Kyverno installation guide
  - `troubleshooting`: Common issues and solutions

**Example Requests**:

1. Get installation help:
```text
Show me how to install Kyverno
```text

2. Get troubleshooting help:
```text
Help me troubleshoot Kyverno issues
```bash

**Example Response**:
```json
{
  "topic": "installation",
  "content": "To install Kyverno using Helm:\n\n1. Add the Kyverno Helm repository:\n   helm repo add kyverno https://kyverno.github.io/kyverno/\n\n2. Install Kyverno:\n   helm install kyverno kyverno/kyverno -n kyverno --create-namespace\n\n..."
}
```json

## Tool Usage Best Practices

### 1. Context Awareness
Always verify the current context before performing operations:
```
What Kubernetes context am I currently using?
```text

### 2. Check Before Apply
Review violations before applying new policies:
```text
First show me current violations, then apply pod security policies
```

### 3. Gradual Policy Adoption
Start with specific policy sets before applying all:
```text
Apply rbac-best-practices first, then we'll add more policies
```

### 4. Test Policy Impact
Test policies to understand their impact on existing resources:
```text
Apply pod security policies and show me what violations occur
```

## Error Handling

All tools include comprehensive error handling:

- **Missing Kyverno**: Installation instructions are provided
- **Invalid Context**: List of valid contexts is shown
- **Policy Conflicts**: Detailed conflict information is returned
- **Network Issues**: Clear error messages with retry suggestions

## Integration Examples

### Complete Security Audit
```text

### Multi-Cluster Management
```text

## Next Steps

- Learn about [Configuration Options](configuration.md)
- Check out [Troubleshooting Guide](troubleshooting.md) 

---

## Configuration


## Configuration Overview

Kyverno MCP can be configured through command-line flags and MCP client configuration files. This guide covers all configuration options and best practices.

## Command Line Options

### Basic Options

| Flag | Description | Default | Example |
|------|-------------|---------|---------|
| `--kubeconfig` | Path to kubeconfig file | `$KUBECONFIG` or `~/.kube/config` | `--kubeconfig=/path/to/config` |
| `--help` | Show help message | - | `--help` |
| `--version` | Show version information | - | `--version` |

### Network Options

| Flag | Description | Default | Example |
|------|-------------|---------|---------|
| `--http-addr` | HTTP(S) server bind address | None (stdio mode) | `--http-addr=:8443` |
| `--tls-cert` | TLS certificate file path | None | `--tls-cert=/path/to/cert.pem` |
| `--tls-key` | TLS private key file path | None | `--tls-key=/path/to/key.pem` |

## MCP Client Configuration

### Claude Desktop

Location:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

Basic configuration:
```json
{
  "mcpServers": {
    "kyverno": {
      "command": "/usr/local/bin/kyverno-mcp",
      "args": [
        "--kubeconfig=/Users/username/.kube/config"
      ]
    }
  }
}
```json

Advanced configuration with multiple clusters:
```json
{
  "mcpServers": {
    "kyverno-prod": {
      "command": "/usr/local/bin/kyverno-mcp",
      "args": [
        "--kubeconfig=/Users/username/.kube/prod-config"
      ]
    },
    "kyverno-staging": {
      "command": "/usr/local/bin/kyverno-mcp",
      "args": [
        "--kubeconfig=/Users/username/.kube/staging-config"
      ]
    }
  }
}
```json

### Other MCP Clients

For other MCP-compatible clients, use similar configuration patterns:

```json
{
  "servers": [
    {
      "name": "kyverno",
      "transport": "stdio",
      "command": {
        "path": "/path/to/kyverno-mcp",
        "args": ["--kubeconfig=/path/to/kubeconfig"]
      }
    }
  ]
}
```text

## Network Mode Configuration

### HTTPS Configuration (Production)

For production deployments, always use HTTPS:

1. Generate TLS certificates:
```bash
# Using OpenSSL
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Using certbot for Let's Encrypt
certbot certonly --standalone -d kyverno-mcp.example.com
```text

2. Start the server:
```bash
kyverno-mcp \
  --http-addr :8443 \
  --tls-cert /path/to/cert.pem \
  --tls-key /path/to/key.pem
```json

3. Configure your MCP client to connect via HTTPS:
```json
{
  "mcpServers": {
    "kyverno": {
      "url": "https://kyverno-mcp.example.com:8443"
    }
  }
}
```text

### HTTP Configuration (Development Only)

⚠️ **Warning**: Never use plain HTTP in production!

For local development:
```bash
kyverno-mcp --http-addr :8080
```text

## Environment Variables

Kyverno MCP respects standard Kubernetes environment variables:

| Variable | Description | Example |
|----------|-------------|---------|
| `KUBECONFIG` | Default kubeconfig path | `/home/user/.kube/config` |
| `KUBERNETES_MASTER` | API server URL | `https://k8s.example.com:6443` |

## Security Configuration

### Kubeconfig Security

1. **Use separate kubeconfig files** for different environments:
```bash
# Production
kyverno-mcp --kubeconfig=$HOME/.kube/prod-config

# Staging
kyverno-mcp --kubeconfig=$HOME/.kube/staging-config
```text

2. **Limit permissions** in kubeconfig:
```yaml
users:
- name: kyverno-mcp
  user:
    token: <service-account-token>
```

3. **Use service accounts** instead of user credentials:
```bash
kubectl create sa kyverno-mcp -n kyverno
kubectl create clusterrolebinding kyverno-mcp --clusterrole=cluster-admin --serviceaccount=kyverno:kyverno-mcp
```

### Network Security

1. **Always use TLS** in production
2. **Implement network policies** to restrict access
3. **Use a reverse proxy** (nginx, HAProxy) for additional security layers

Example nginx configuration:
```nginx
server {
    listen 443 ssl;
    server_name kyverno-mcp.example.com;
    
    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## Performance Tuning

### Connection Pooling

For high-traffic scenarios, configure connection pooling:

```bash
// This is handled internally, but you can tune via environment variables
export GOGC=100  # Garbage collection target percentage
export GOMAXPROCS=4  # Maximum number of CPUs
```

### Resource Limits

When running in containers, set appropriate resource limits:

```yaml
resources:
  requests:
    memory: "64Mi"
    cpu: "250m"
  limits:
    memory: "128Mi"
    cpu: "500m"
```

## Logging and Debugging

### Enable Debug Logging

```bash
kyverno-mcp --log-level=debug
```

### Log Formats

- **Text** (default): Human-readable logs
- **JSON**: Structured logs for parsing

```bash
kyverno-mcp --log-format=json
```

## Configuration Best Practices

1. **Separate Configurations**: Use different configurations for different environments
2. **Version Control**: Store configurations in version control (excluding secrets)
3. **Secret Management**: Use proper secret management tools for sensitive data
4. **Regular Updates**: Keep configurations up to date with security patches
5. **Monitoring**: Configure logging and monitoring for production deployments

## Next Steps

- Learn about [Troubleshooting](troubleshooting.md)

---

## Troubleshooting


## Common Issues

This guide covers common issues you might encounter when using Kyverno MCP and their solutions.

## Installation Issues

### Command Not Found

**Problem**: After installation, `kyverno-mcp` command is not found.

**Solution**:
1. Check if the binary is in your PATH:
   ```bash
   echo $PATH
   ```
2. If using Homebrew, ensure it's properly linked:
   ```bash
   brew link kyverno-mcp
   ```
3. For manual installation, add to PATH:
   ```bash
   export PATH=$PATH:/path/to/kyverno-mcp
   echo 'export PATH=$PATH:/path/to/kyverno-mcp' >> ~/.bashrc
   ```

### Permission Denied

**Problem**: Getting "permission denied" when trying to run kyverno-mcp.

**Solution**:
```bash
chmod +x kyverno-mcp
```text

## Connection Issues

### Cannot Connect to Kubernetes Cluster

**Problem**: Error messages like "unable to connect to cluster" or "no configuration has been provided".

**Solutions**:

1. **Verify kubeconfig exists**:
   ```bash
   ls ~/.kube/config
   ```

2. **Test kubectl connection**:
   ```bash
   kubectl cluster-info
   ```

3. **Specify kubeconfig explicitly**:
   ```bash
   kyverno-mcp --kubeconfig=/path/to/your/kubeconfig
   ```

4. **Check kubeconfig permissions**:
   ```bash
   chmod 600 ~/.kube/config
   ```

### Context Not Found

**Problem**: "context not found" error when switching contexts.

**Solution**:
1. List available contexts:
   ```bash
   kubectl config get-contexts
   ```
2. Use the exact context name from the list

## MCP Client Issues

### Server Not Appearing in Claude Desktop

**Problem**: Kyverno MCP server doesn't show up in Claude Desktop.

**Solutions**:

1. **Check configuration file location**:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. **Validate JSON syntax**:
   ```bash
   # Use jq or similar tool
   jq . claude_desktop_config.json
   ```

3. **Ensure correct path**:
   ```json
   {
     "mcpServers": {
       "kyverno": {
         "command": "/usr/local/bin/kyverno-mcp",  // Full path
         "args": ["--kubeconfig=/Users/username/.kube/config"]
       }
     }
   }
   ```

4. **Restart Claude Desktop** after configuration changes

### Tools Not Available

**Problem**: AI assistant says Kyverno tools are not available.

**Solution**:
1. Check if the server is running properly
2. Look for error messages in Claude Desktop logs
3. Try running kyverno-mcp directly to see any errors:
   ```bash
   kyverno-mcp --kubeconfig=/path/to/config
   ```

## Policy Issues

### Policies Not Being Applied

**Problem**: Running `apply_policies` but policies don't appear in the cluster.

**Solutions**:

1. **Check Kyverno installation**:
   ```bash
   kubectl get pods -n kyverno
   ```

2. **Verify cluster permissions**:
   ```bash
   kubectl auth can-i create clusterpolicies
   ```

3. **Check for existing policies**:
   ```bash
   kubectl get cpol
   ```

4. **Look for policy conflicts**:
   ```bash
   kubectl describe cpol <policy-name>
   ```

### No Violations Showing

**Problem**: `show_violations` returns empty results despite policy violations.

**Solutions**:

1. **Verify PolicyReport CRDs are installed**:
   ```bash
   kubectl get crd | grep policyreport
   ```

2. **Check if reports are being generated**:
   ```bash
   kubectl get policyreport -A
   kubectl get clusterpolicyreport
   ```

3. **Ensure policies are in enforce mode**:
   ```bash
   kubectl get cpol -o yaml | grep validationFailureAction
   ```

## Network Mode Issues

### TLS Certificate Errors

**Problem**: TLS handshake errors when using HTTPS mode.

**Solution**:
1. Verify certificate validity:
   ```bash
   openssl x509 -in cert.pem -text -noout
   ```

2. Check certificate matches the hostname:
   ```bash
   openssl s_client -connect kyverno-mcp.example.com:8443
   ```

3. Ensure proper certificate chain if using CA-signed certs

### Port Already in Use

**Problem**: "address already in use" error.

**Solution**:
1. Find what's using the port:
   ```bash
   lsof -i :8443  # macOS/Linux
   netstat -ano | findstr :8443  # Windows
   ```

2. Kill the process or use a different port:
   ```bash
   kyverno-mcp --http-addr :8444
   ```

## Performance Issues

### Slow Response Times

**Problem**: Tools taking a long time to respond.

**Solutions**:

1. **Check cluster latency**:
   ```bash
   time kubectl get nodes
   ```

2. **Reduce resource queries**:
   - Use namespace filters when checking violations
   - Apply policies to specific namespaces first

3. **Check resource limits** if running in a container

## Debugging Tips

### Enable Debug Logging

Get more detailed output:
```bash
kyverno-mcp --log-level=debug
```text

### Check MCP Protocol Messages

For stdio mode, you can intercept messages:
```bash
# Create a wrapper script
cat > debug-kyverno-mcp.sh << 'EOF'
#!/bin/bash
tee -a kyverno-mcp-input.log | kyverno-mcp "$@" | tee -a kyverno-mcp-output.log
EOF
chmod +x debug-kyverno-mcp.sh
```

### Common Error Messages

| Error | Meaning | Solution |
|-------|---------|----------|
| `no kind "ClusterPolicy" is registered` | Kyverno CRDs not installed | Install Kyverno first |
| `unauthorized` | Insufficient permissions | Check RBAC settings |
| `context deadline exceeded` | Network timeout | Check connectivity |
| `certificate signed by unknown authority` | Custom CA not trusted | Add CA to trust store |

## Getting Help

If you're still experiencing issues:

1. **Check existing issues**: [GitHub Issues](https://github.com/nirmata/kyverno-mcp/issues)
2. **Enable debug logging** and collect logs
3. **Gather environment information**:
   ```bash
   kyverno-mcp --version
   kubectl version
   go version  # if built from source
   ```
4. **Create a detailed issue** with:
   - Steps to reproduce
   - Expected vs actual behavior
   - Environment details
   - Relevant logs

## Next Steps

- Review [Configuration Options](configuration.md)