MKP - Model Kontext Protocol Server for Kubernetes

<p align="center">

</p>

MKP is a Model Context Protocol (MCP) server for Kubernetes that allows
LLM-powered applications to interact with Kubernetes clusters. It provides tools
for listing and applying Kubernetes resources through the MCP protocol.

Features

- List resources supported by the Kubernetes API server
- List clustered resources
- List namespaced resources
- Get resources and their subresources (including status, scale, logs, etc.)
- Apply (create or update) clustered resources
- Apply (create or update) namespaced resources
- Execute commands in pods with timeout control
- Generic and pluggable implementation using API Machinery's unstructured client
- Built-in rate limiting for protection against excessive API calls

Why MKP?

MKP offers several key advantages as a Model Context Protocol server for
Kubernetes:

Native Go Implementation

- Built with the same language as Kubernetes itself
- Excellent performance characteristics for server applications
- Strong type safety and concurrency support
- Seamless integration with Kubernetes libraries

Direct API Integration

- Uses Kubernetes API machinery directly without external dependencies
- No reliance on kubectl, helm, or other CLI tools
- Communicates directly with the Kubernetes API server
- Reduced overhead and improved reliability

Universal Resource Support

- Works with any Kubernetes resource type through the unstructured client
- No hardcoded resource schemas or specialized handlers needed
- Automatically supports Custom Resource Definitions (CRDs)
- Future-proof for new Kubernetes resources

Minimalist Design

- Focused on core Kubernetes resource operations
- Clean, maintainable codebase with clear separation of concerns
- Lightweight with minimal dependencies
- Easy to understand, extend, and contribute to

Production-Ready Architecture

- Designed for reliability and performance in production environments
- Proper error handling and resource management
- Built-in rate limiting to protect against excessive API calls
- Testable design with comprehensive unit tests
- Follows Kubernetes development best practices

Prerequisites

- Go 1.24 or later
- Kubernetes cluster and kubeconfig
- Task for running tasks

Installation

1. Clone the repository:

   git clone https://github.com/StacklokLabs/mkp.git
   cd mkp
   

2. Install dependencies:

   task install
   

3. Build the server:

   task build
   

Usage

Running the server

To run the server with the default kubeconfig:

task run

To run the server with a specific kubeconfig:

KUBECONFIG=/path/to/kubeconfig task run-with-kubeconfig

To run the server on a specific port:

MCP_PORT=9091 task run

Running with ToolHive

MKP can be run as a Model Context Protocol (MCP) server using
ToolHive, which simplifies the
deployment and management of MCP servers.

See the
ToolHive documentation for
detailed instructions on how to set up MKP with the ToolHive UI, CLI, or
Kubernetes operator.

MCP Tools

The MKP server provides the following MCP tools:

get_resource

Get a Kubernetes resource or its subresource.

Parameters:

- resource_type (required): Type of resource to get (clustered or namespaced)
- group: API group (e.g., apps, networking.k8s.io)
- version (required): API version (e.g., v1, v1beta1)
- resource (required): Resource name (e.g., deployments, services)
- namespace: Namespace (required for namespaced resources)
- name (required): Name of the resource to get
- subresource: Subresource to get (e.g., status, scale, logs)
- parameters: Optional parameters for the request (see examples below)

Example:

{
  "name": "get_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default",
    "name": "nginx-deployment",
    "subresource": "status"
  }
}

Example of getting logs from a specific container with parameters:

{
  "name": "get_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "name": "my-pod",
    "subresource": "logs",
    "parameters": {
      "container": "my-container",
      "sinceSeconds": "3600",
      "timestamps": "true",
      "limitBytes": "102400"
    }
  }
}

Available parameters for pod logs:

- container: Specify which container to get logs from
- previous: Get logs from previous container instance (true/false)
- sinceSeconds: Only return logs newer than a relative duration in seconds
- sinceTime: Only return logs after a specific time (RFC3339 format)
- timestamps: Include timestamps on each line (true/false)
- limitBytes: Maximum number of bytes to return
- tailLines: Number of lines to return from the end of the logs

By default, pod logs are limited to the last 100 lines and 32KB to avoid
overwhelming the LLM's context window. These defaults can be overridden using
the parameters above.

Available parameters for regular resources:

- resourceVersion: When specified, shows the resource at that particular
version

list_resources

Lists Kubernetes resources of a specific type.

Parameters:

- resource_type (required): Type of resource to list (clustered or namespaced)
- group: API group (e.g., apps, networking.k8s.io)
- version (required): API version (e.g., v1, v1beta1)
- resource (required): Resource name (e.g., deployments, services)
- namespace: Namespace (required for namespaced resources)
- label_selector: Kubernetes label selector for filtering resources (optional)
- include_annotations: Whether to include annotations in the output (default:
true)
- exclude_annotation_keys: List of annotation keys to exclude from output
(supports wildcards with \)
- include_annotation_keys: List of annotation keys to include in output (if
specified, only these are included)

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default"
  }
}

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "clustered",
    "group": "",
    "version": "v1",
    "resource": "nodes",
    "exclude_annotation_keys": [
      "nvidia.com/",
      "kubectl.kubernetes.io/last-applied-configuration"
    ]
  }
}

Include only specific annotations:

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "include_annotation_keys": ["app", "version", "prometheus.io/scrape"]
  }
}

Disable annotations completely for maximum performance:

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "include_annotations": false
  }
}

Annotation Filtering Rules:

- By default, kubectl.kubernetes.io/last-applied-configuration is excluded to
prevent large configuration data
- exclude_annotation_keys supports wildcard patterns using (e.g.,
nvidia.com/ excludes all NVIDIA annotations)
- When include_annotation_keys is specified, it takes precedence and only
those annotations are included
- Setting include_annotations: false completely removes all annotations from
the output
- Wildcard patterns only support at the end of the key (e.g.,
nvidia.com/)

apply_resource

Applies (creates or updates) a Kubernetes resource.

Parameters:

- resource_type (required): Type of resource to apply (clustered or
namespaced)
- group: API group (e.g., apps, networking.k8s.io)
- version (required): API version (e.g., v1, v1beta1)
- resource (required): Resource name (e.g., deployments, services)
- namespace: Namespace (required for namespaced resources)
- manifest (required): Resource manifest

Example:

{
  "name": "apply_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default",
    "manifest": {
      "apiVersion": "apps/v1",
      "kind": "Deployment",
      "metadata": {
        "name": "nginx-deployment",
        "namespace": "default"
      },
      "spec": {
        "replicas": 3,
        "selector": {
          "matchLabels": {
            "app": "nginx"
          }
        },
        "template": {
          "metadata": {
            "labels": {
              "app": "nginx"
            }
          },
          "spec": {
            "containers": [
              {
                "name": "nginx",
                "image": "nginx:latest",
                "ports": [
                  {
                    "containerPort": 80
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }
}

post_resource

Posts to a Kubernetes resource or its subresource, particularly useful for
executing commands in pods.

Parameters:

- resource_type (required): Type of resource to post to (clustered or
namespaced)
- group: API group (e.g., apps, networking.k8s.io)
- version (required): API version (e.g., v1, v1beta1)
- resource (required): Resource name (e.g., deployments, services)
- namespace: Namespace (required for namespaced resources)
- name (required): Name of the resource to post to
- subresource: Subresource to post to (e.g., exec)
- body (required): Body to post to the resource
- parameters: Optional parameters for the request

Example of executing a command in a pod:

{
  "name": "post_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "name": "my-pod",
    "subresource": "exec",
    "body": {
      "command": ["ls", "-la", "/"],
      "container": "my-container",
      "timeout": 30
    }
  }
}

The body for pod exec supports the following fields:

- command (required): Command to execute, either as a string or an array of
strings
- container (optional): Container name to execute the command in (defaults to
the first container)
- timeout (optional): Timeout in seconds (defaults to 15 seconds, maximum 60
seconds)

Note on timeouts:

- Default timeout: 15 seconds if not specified
- Maximum timeout: 60 seconds (any larger value will be capped)
- Commands that exceed the timeout will be terminated and return a timeout error

The response includes stdout, stderr, and any error message:

{
  "apiVersion": "v1",
  "kind": "Pod",
  "metadata": {
    "name": "my-pod",
    "namespace": "default"
  },
  "spec": {
    "command": ["ls", "-la", "/"]
  },
  "status": {
    "stdout": "total 48\ndrwxr-xr-x   1 root root 4096 May  5 14:30 .\ndrwxr-xr-x   1 root root 4096 May  5 14:30 ..\n...",
    "stderr": "",
    "error": ""
  }
}

MCP Resources

The MKP server provides access to Kubernetes resources through MCP resources.
The resource URIs follow these formats:

- Clustered resources: k8s://clustered/{group}/{version}/{resource}/{name}
- Namespaced resources:
k8s://namespaced/{namespace}/{group}/{version}/{resource}/{name}

Configuration

Transport Protocol

MKP supports two transport protocols for the MCP server:

- Streamable HTTP: The default transport protocol, suitable for most use cases
- SSE (Server-Sent Events): Legacy transport protocol, primarily for compatibility with older clients

You can configure the transport protocol using either a CLI flag or an
environment variable:

```bash