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:

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

Claude Code

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

Claude Desktop

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

Gemini CLI

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

VS Code

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:

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

kubectl-ai

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.

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:

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

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:

Config:

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:

Config:

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:

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