Kubescape MCP Server

The Kubescape MCP (Model Context Protocol) Server enables AI assistants to query your Kubernetes cluster's security posture using natural language. It exposes Kubescape's vulnerability and configuration scan data through the MCP protocol.

Overview

The MCP server allows AI assistants (like Claude, ChatGPT, or custom AI tools) to:

• List and query vulnerability manifests for images and workloads
• Retrieve CVE details and vulnerability matches
• Access configuration security scan results
• Provide security recommendations based on real cluster data

Prerequisites

Before using the MCP server, you need:

1. Kubescape Operator installed in your cluster - The MCP server reads data from Custom Resources created by the operator
2. kubectl configured - With access to the cluster running the Kubescape operator
3. Kubescape CLI - Version 3.x or later

Installing the Kubescape Operator

helm repo add kubescape https://kubescape.github.io/helm-charts/
helm repo update

helm upgrade --install kubescape kubescape/kubescape-operator \
  --namespace kubescape \
  --create-namespace \
  --set capabilities.vulnerabilityScan=enable \
  --set capabilities.configurationScan=enable

Wait for the operator to complete initial scans:

kubectl -n kubescape get vulnerabilitymanifests
kubectl -n kubescape get workloadconfigurationscans

Starting the MCP Server

kubescape mcpserver

The server starts and communicates via stdio, making it compatible with MCP-enabled AI tools.

Available Tools

The MCP server exposes the following tools to AI assistants:

Vulnerability Tools

list_vulnerability_manifests

Discover available vulnerability manifests at image and workload levels.

Parameters:

Example Response:

{
  "vulnerability_manifests": {
    "manifests": [
      {
        "type": "workload",
        "namespace": "default",
        "manifest_name": "deployment-nginx-nginx",
        "image-level": false,
        "workload-level": true,
        "image-id": "sha256:abc123...",
        "image-tag": "nginx:1.21",
        "resource_uri": "kubescape://vulnerability-manifests/default/deployment-nginx-nginx"
      }
    ]
  }
}

list_vulnerabilities_in_manifest

List all vulnerabilities (CVEs) found in a specific manifest.

Parameters:

Example Response:

[
  {
    "id": "CVE-2023-12345",
    "severity": "High",
    "description": "Buffer overflow in libfoo",
    "fix": {
      "versions": ["1.2.4"],
      "state": "fixed"
    }
  }
]

list_vulnerability_matches_for_cve

Get detailed information about a specific CVE in a manifest, including affected packages and fix information.

Parameters:

Configuration Tools

list_configuration_security_scan_manifests

Discover available security configuration scan results at the workload level.

Parameters:

Example Response:

{
  "configuration_manifests": {
    "manifests": [
      {
        "namespace": "default",
        "manifest_name": "deployment-nginx",
        "resource_uri": "kubescape://configuration-manifests/default/deployment-nginx"
      }
    ]
  }
}

get_configuration_security_scan_manifest

Get detailed configuration scan results for a specific workload, including failed controls and remediation guidance.

Parameters:

Live Scanning Tools

run_framework_security_scan

Run an on-demand, live Framework security scan (e.g. nsa, mitre) and return the failed resources along with the compliance score. Check the degraded flag in the response to ensure the scan fully completed (e.g. no control timeouts). Note that compliance_score is optional and may be omitted if the scan produces no framework summary. The failed_resources array is truncated at 100 entries; check truncated, total_failed, and returned_failed to understand if the list is partial.

Parameters:

Example Response:

{
  "compliance_score": 0,
  "framework_name": "nsa",
  "degraded": true,
  "not_evaluated_controls": 8,
  "total_controls": 24,
  "total_failed": 5,
  "returned_failed": 5,
  "truncated": false,
  "failed_resources": [{}, {}, {}, {}, {}]
}

run_rbac_security_scan

Run an on-demand, live RBAC security scan (evaluating RBAC-related controls) and return the failed resources. The failed_resources array is truncated at 100 entries; check truncated, total_failed, and returned_failed to understand if the list is partial.

Parameters:

Example Response:

{
  "degraded": false,
  "not_evaluated_controls": 0,
  "total_controls": 2,
  "total_failed": 1,
  "returned_failed": 1,
  "truncated": false,
  "failed_resources": [{}]
}

run_network_security_scan

Run an on-demand, live Network security scan (evaluating network-related controls) and return the failed resources. The failed_resources array is truncated at 100 entries; check truncated, total_failed, and returned_failed to understand if the list is partial.

Parameters:

Example Response:

{
  "degraded": false,
  "not_evaluated_controls": 0,
  "total_controls": 1,
  "total_failed": 0,
  "returned_failed": 0,
  "truncated": false,
  "failed_resources": []
}

scan_container_image

Run an on-demand container image vulnerability scan and return structured JSON containing deduplicated vulnerabilities, severity counts, and optional match details.

Parameters:

Example Response:

{
  "image": "nginx:alpine",
  "total_vulnerabilities": 1,
  "severities": {
    "Critical": 1
  },
  "vulnerabilities": [
    {
      "id": "CVE-2023-12345",
      "severity": "Critical",
      "package": {
        "name": "libssl",
        "version": "1.1.1"
      }
    }
  ]
}

Resource Templates

The MCP server also exposes resource templates for direct access to data:

Vulnerability Manifest

kubescape://vulnerability-manifests/{namespace}/{manifest_name}

Configuration Manifest

kubescape://configuration-manifests/{namespace}/{manifest_name}

Integration with AI Assistants

Claude Desktop

Add to your Claude Desktop configuration (~/.config/claude/config.json on Linux or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "kubescape": {
      "command": "kubescape",
      "args": ["mcpserver"]
    }
  }
}

Custom Integration

For custom AI applications using the MCP SDK:

from mcp import Client

async with Client("kubescape", ["kubescape", "mcpserver"]) as client:
    # List vulnerability manifests
    result = await client.call_tool(
        "list_vulnerability_manifests",
        {"level": "workload"}
    )
    print(result)

Example AI Queries

Once connected, you can ask your AI assistant questions like:

• "What vulnerabilities exist in my production namespace?"
• "Show me all critical CVEs affecting my nginx deployments"
• "What configuration issues does my cluster have?"
• "Which workloads have the most security issues?"
• "Give me details about CVE-2023-12345 in my cluster"

Troubleshooting

No vulnerability manifests found

Ensure the Kubescape operator has completed vulnerability scanning:

kubectl -n kubescape get vulnerabilitymanifests

If empty, check operator logs:

kubectl -n kubescape logs -l app=kubescape

Connection issues

Verify your kubeconfig is correctly configured:

kubectl get nodes

MCP server not responding

Check that you're running Kubescape v3.x or later:

kubescape version

Security Considerations

• The MCP server runs with the same Kubernetes permissions as your kubeconfig
• It provides read-only access to vulnerability and configuration data
• No cluster modifications are made through the MCP server
• Consider running with a service account that has limited permissions in production
• Credential Handling: The scan_container_image tool accepts optional registry credentials (username and password). Be aware that parameters supplied to MCP tools may be retained in client conversation logs or model contexts depending on your client environment.
• Image Reference Validation: The scan_container_image tool validates image names as remote image references and rejects local file paths and scheme prefixes (such as dir:, file:, sbom:) to prevent unauthorized local filesystem access.
• Air-Gapped Environments: In air-gapped environments, set the KS_GRYPE_LISTING_URL environment variable to point to your internal Grype vulnerability database mirror listing URL.

Related Documentation

• Kubescape Operator Installation
• Vulnerability Scanning
• Configuration Scanning
• MCP Protocol Specification