Kyverno MCP Server on Nirmata Documentation

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

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)

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

Start your MCP client (e.g., Claude Desktop)
Ask about your Kubernetes contexts:

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.

Usage

Mon, 01 Jan 0001 00:00:00 +0000

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.”

Installation

Mon, 01 Jan 0001 00:00:00 +0000

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:

# 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:

Available Tools

Mon, 01 Jan 0001 00:00:00 +0000

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:

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?

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

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:

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

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:

Check if the binary is in your PATH:
```
echo $PATH
```
If using Homebrew, ensure it’s properly linked:
```
brew link kyverno-mcp
```

For manual installation, add to PATH:

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.