kube-audit-mcp

English | 简体中文

kube-audit-mcp is a Model Context Protocol (MCP) server that gives AI agents, assistants, and chatbots the ability to query Kubernetes Audit Logs.

Table of Contents

• Installation
• MCP Clients
  • Claude Code
  • Claude Desktop
  • Gemini CLI
  • VS Code
  • kubectl-ai
• Transport Options
  • STDIO Transport (Default)
• Configurations
  • Sample Config
  • Provider
    • Alibaba Cloud Log Service
    • AWS CloudWatch Logs
    • Google Cloud Logging
• Available Tools
  • query_audit_log
  • list_clusters
  • list_common_resource_types

Installation

1. First, download and install the latest release from the releases page.

   • You can also install via docker:

     docker pull quay.io/mozillazg/kube-audit-mcp:latest
     

2. Then, configure the provider of Kubernetes Audit Logs. See Configurations for details.

MCP Clients

Theoretically, any MCP client should work with kube-audit-mcp.

Standard config works in most of the clients:

{
  "mcpServers": {
    "kube-audit": {
      "type": "stdio",
      "command": "kube-audit-mcp",
      "args": [
        "mcp"
      ]
    }
  }
}

<details> <summary>Run with docker</summary>

You can also run kube-audit-mcp via docker, use the following config:

{
  "mcpServers": {
    "kube-audit": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/etc/kube-audit-mcp/config.yaml:/etc/kube-audit-mcp/config.yaml:ro",
        "quay.io/mozillazg/kube-audit-mcp:latest",
        "mcp",
        "--config",
        "/etc/kube-audit-mcp/config.yaml"
      ],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "needed_if_you_use_alibaba_sls_provider",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "needed_if_you_use_alibaba_sls_provider",
        "AWS_ACCESS_KEY_ID": "needed_if_you_use_aws_cloudwatch_logs_provider",
        "AWS_SECRET_ACCESS_KEY": "needed_if_you_use_aws_cloudwatch_logs_provider",
        "GOOGLE_APPLICATION_CREDENTIALS": "needed_if_you_use_gcp_cloud_logging_provider"
      }
    }
  }
}

</details>

Claude Code

<details>

Use the Claude Code CLI to add the kube-audit-mcp:

claude mcp add kube-audit kube-audit-mcp mcp

</details>

Claude Desktop

<details>

Follow the MCP install guide, use the standard config above.

</details>

Gemini CLI

<details>

Follow the MCP install guide, use the standard config above.

</details>

VS Code

<details>

Follow the MCP install guide, use the standard config above. You can also install the kube-audit-mcp MCP server using the VS Code CLI:

# For VS Code
code --add-mcp '''{"name":"kube-audit","command":"kube-audit-mcp","args":["mcp"]}'''

After installation, the kube-audit-mcp MCP server will be available for use with your GitHub Copilot agent in VS Code.

</details>

kubectl-ai

<details> Follow the MCP install guide, use the config like below:

servers:
  # Local MCP server (stdio-based)
  - name: kube-audit
    command: kube-audit-mcp
    args:
      - mcp

</details>

Transport Options

STDIO Transport (Default)

The default transport mode uses standard input/output for communication. This is the standard MCP transport used by most clients like Claude Desktop.

# Run with default stdio transport
kube-audit-mcp mcp

# Or explicitly specify stdio
kube-audit-mcp mcp --transport stdio

Configurations

kube-audit-mcp requires a configuration file to specify the provider of Kubernetes Audit Logs. The configuration file is typically located at ~/.config/kube-audit-mcp/config.yaml or specified via the --config flag.

Sample Config

You can get a sample config via the following command:

kube-audit-mcp sample-config

<details>

<summary>Here is a sample configuration file</summary>

default_cluster: prod              # The default cluster to use
clusters:                          # List of clusters
  - name: prod                     # Name of the cluster
    provider:                      # Provider configuration, see below for details
      name: aws-cloudwatch-logs    # Use CloudWatch Logs as the provider
      aws_cloudwatch_logs:
        log_group_name: /aws/eks/test/cluster  # Replace with your CloudWatch Logs log group name
  - name: dev                     # Name of the cluster
    provider:
      name: alibaba-sls            # Use Alibaba Cloud Log Service as the provider
      alibaba_sls:
        endpoint: cn-hangzhou.log.aliyuncs.com  # Replace with your Log Service endpoint
        project: k8s-log-cxxx                   # Replace with your Log Service project
        logstore: audit-cxxx                    # Replace with your Log Service logstore
  - name: test
    provider:
      name: gcp-cloud-logging      # Use Google Cloud Logging as the provider
      gcp_cloud_logging:
        project_id: test-233xxx # Replace with your Project ID
        cluster_name: test-cluster  # Replace with your GKE cluster name (optional)

</details>

Or save the sample configuration to the default config file location:

kube-audit-mcp sample-config --save

Provider

Alibaba Cloud Log Service

Prerequisites:

• Install and configure the Alibaba Cloud CLI with credentials
• Ensure your Alibaba Cloud user or role has the necessary permissions to read from the specified Log Service project and logstore. The following policy can be used to grant the necessary permissions:

<details>

<summary>RAM permissions</summary>

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "log:GetLogStoreLogs"
      ],
      "Resource": "*"
    }
  ]
}

</details>

Config:

name: alibaba-sls
alibaba_sls:
  endpoint: cn-hangzhou.log.aliyuncs.com  # Replace with your Log Service endpoint
  logstore: ${log_store}                  # Replace with your Log Service logstore
  project: ${project_name}                # Replace with your Log Service project

AWS CloudWatch Logs

Prerequisites:

• Install and configure the AWS CLI with credentials
• Ensure your AWS IAM user or role has the necessary permissions to read from the specified CloudWatch Logs log group. The following policy can be used to grant the necessary permissions:

<details>

<summary>IAM permissions</summary>

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "logs:StartQuery",
        "logs:GetQueryResults"
      ],
      "Resource": "*"
    }
  ]
}

</details>

Config:

name: aws-cloudwatch-logs
aws_cloudwatch_logs:
  log_group_name: /aws/eks/${cluster_name}/cluster # Replace with your CloudWatch Logs log group name

Google Cloud Logging

Prerequisites:

• Install and configure the Google Cloud CLI with Application Default Credentials
• Ensure your Google Cloud IAM user or service account has the necessary permissions to read from the specified Cloud Logging log bucket. The following role can be used to grant the necessary permissions: roles/logging.viewer.

Config:

name: gcp-cloud-logging
gcp_cloud_logging:
  project_id: ${project_id}         # Replace with your Project ID
  cluster_name: ${cluster_name}     # Replace with your GKE cluster name (optional)

Available Tools

This MCP server exposes the following tools to the AI agent:

query_audit_log

Queries the Kubernetes audit logs from the configured provider. This is the primary tool for investigating activity in your clusters.

Parameters:

• cluster_name (string, optional): The name of the cluster to query. You can see available clusters with the list_clusters tool. Defaults to the configured default_cluster.
• start_time (string, optional): The start time for the query. Can be in ISO 8601 format (2024-01-01T10:00:00) or relative time (7d, 1h, 30m). Defaults to 7d.
• end_time (string, optional): The end time for the query. If omitted, defaults to the current time.
• limit (number, optional): The maximum number of log entries to return. Defaults to 10, with a maximum of 20.
• namespace (string, optional): Filter logs by a specific namespace. Supports suffix wildcards (e.g., kube-*).
• resource_types (array of strings, optional): Filter by one or more Kubernetes resource types (e.g., pods, deployments). Supports short names (e.g., po, deploy). Use list_common_resource_types to discover available types.
• resource_name (string, optional): Filter by a specific resource name. Supports suffix wildcards.
• verbs (array of strings, optional): Filter by one or more action verbs (e.g., create, delete, update).
• user (string, optional): Filter by the user who performed the action. Supports suffix wildcards.

list_clusters

Lists all clusters that are configured in the config.yaml file. This is useful for discovering which clusters you can target for queries.

Parameters: None

list_common_resource_types

Returns a list of common Kubernetes resource types, grouped by category (e.g., "Core Resources", "Apps Resources"). This helps in finding the correct value for the resource_types parameter in the query_audit_log tool.

Parameters: None