MKP - Model Kontext Protocol Server for Kubernetes

1# MKP - Model Kontext Protocol Server for Kubernetes
2 
3<p align="center">
4  <img src="docs/assets/mkp-logo.png" width="400" alt="MKP Logo">
5</p>
6 
7MKP is a Model Context Protocol (MCP) server for Kubernetes that allows
8LLM-powered applications to interact with Kubernetes clusters. It provides tools
9for listing and applying Kubernetes resources through the MCP protocol.
10 
11## Features
12 
13- List resources supported by the Kubernetes API server
14- List clustered resources
15- List namespaced resources
16- Get resources and their subresources (including status, scale, logs, etc.)
17- Apply (create or update) clustered resources
18- Apply (create or update) namespaced resources
19- Execute commands in pods with timeout control
20- Generic and pluggable implementation using API Machinery's unstructured client
21- Built-in rate limiting for protection against excessive API calls
22 
23## Why MKP?
24 
25MKP offers several key advantages as a Model Context Protocol server for
26Kubernetes:
27 
28### Native Go Implementation
29 
30- Built with the same language as Kubernetes itself
31- Excellent performance characteristics for server applications
32- Strong type safety and concurrency support
33- Seamless integration with Kubernetes libraries
34 
35### Direct API Integration
36 
37- Uses Kubernetes API machinery directly without external dependencies
38- No reliance on kubectl, helm, or other CLI tools
39- Communicates directly with the Kubernetes API server
40- Reduced overhead and improved reliability
41 
42### Universal Resource Support
43 
44- Works with any Kubernetes resource type through the unstructured client
45- No hardcoded resource schemas or specialized handlers needed
46- Automatically supports Custom Resource Definitions (CRDs)
47- Future-proof for new Kubernetes resources
48 
49### Minimalist Design
50 
51- Focused on core Kubernetes resource operations
52- Clean, maintainable codebase with clear separation of concerns
53- Lightweight with minimal dependencies
54- Easy to understand, extend, and contribute to
55 
56### Production-Ready Architecture
57 
58- Designed for reliability and performance in production environments
59- Proper error handling and resource management
60- Built-in rate limiting to protect against excessive API calls
61- Testable design with comprehensive unit tests
62- Follows Kubernetes development best practices
63 
64## Prerequisites
65 
66- Go 1.24 or later
67- Kubernetes cluster and kubeconfig
68- [Task](https://taskfile.dev/) for running tasks
69 
70## Installation
71 
721. Clone the repository:
73 
74   ```bash
75   git clone https://github.com/StacklokLabs/mkp.git
76   cd mkp
77   ```
78 
792. Install dependencies:
80 
81   ```bash
82   task install
83   ```
84 
853. Build the server:
86 
87   ```bash
88   task build
89   ```
90 
91## Usage
92 
93### Running the server
94 
95To run the server with the default kubeconfig:
96 
97```bash
98task run
99```
100 
101To run the server with a specific kubeconfig:
102 
103```bash
104KUBECONFIG=/path/to/kubeconfig task run-with-kubeconfig
105```
106 
107To run the server on a specific port:
108 
109```bash
110MCP_PORT=9091 task run
111```
112 
113## Running with ToolHive
114 
115MKP can be run as a Model Context Protocol (MCP) server using
116[ToolHive](https://github.com/stacklok/toolhive), which simplifies the
117deployment and management of MCP servers.
118 
119See the
120[ToolHive documentation](https://docs.stacklok.com/toolhive/guides-mcp/k8s) for
121detailed instructions on how to set up MKP with the ToolHive UI, CLI, or
122Kubernetes operator.
123 
124### MCP Tools
125 
126The MKP server provides the following MCP tools:
127 
128#### get_resource
129 
130Get a Kubernetes resource or its subresource.
131 
132Parameters:
133 
134- `resource_type` (required): Type of resource to get (clustered or namespaced)
135- `group`: API group (e.g., apps, networking.k8s.io)
136- `version` (required): API version (e.g., v1, v1beta1)
137- `resource` (required): Resource name (e.g., deployments, services)
138- `namespace`: Namespace (required for namespaced resources)
139- `name` (required): Name of the resource to get
140- `subresource`: Subresource to get (e.g., status, scale, logs)
141- `parameters`: Optional parameters for the request (see examples below)
142 
143Example:
144 
145```json
146{
147  "name": "get_resource",
148  "arguments": {
149    "resource_type": "namespaced",
150    "group": "apps",
151    "version": "v1",
152    "resource": "deployments",
153    "namespace": "default",
154    "name": "nginx-deployment",
155    "subresource": "status"
156  }
157}
158```
159 
160Example of getting logs from a specific container with parameters:
161 
162```json
163{
164  "name": "get_resource",
165  "arguments": {
166    "resource_type": "namespaced",
167    "group": "",
168    "version": "v1",
169    "resource": "pods",
170    "namespace": "default",
171    "name": "my-pod",
172    "subresource": "logs",
173    "parameters": {
174      "container": "my-container",
175      "sinceSeconds": "3600",
176      "timestamps": "true",
177      "limitBytes": "102400"
178    }
179  }
180}
181```
182 
183Available parameters for pod logs:
184 
185- `container`: Specify which container to get logs from
186- `previous`: Get logs from previous container instance (true/false)
187- `sinceSeconds`: Only return logs newer than a relative duration in seconds
188- `sinceTime`: Only return logs after a specific time (RFC3339 format)
189- `timestamps`: Include timestamps on each line (true/false)
190- `limitBytes`: Maximum number of bytes to return
191- `tailLines`: Number of lines to return from the end of the logs
192 
193By default, pod logs are limited to the last 100 lines and 32KB to avoid
194overwhelming the LLM's context window. These defaults can be overridden using
195the parameters above.
196 
197Available parameters for regular resources:
198 
199- `resourceVersion`: When specified, shows the resource at that particular
200  version
201 
202#### list_resources
203 
204Lists Kubernetes resources of a specific type.
205 
206Parameters:
207 
208- `resource_type` (required): Type of resource to list (clustered or namespaced)
209- `group`: API group (e.g., apps, networking.k8s.io)
210- `version` (required): API version (e.g., v1, v1beta1)
211- `resource` (required): Resource name (e.g., deployments, services)
212- `namespace`: Namespace (required for namespaced resources)
213- `label_selector`: Kubernetes label selector for filtering resources (optional)
214- `include_annotations`: Whether to include annotations in the output (default:
215  true)
216- `exclude_annotation_keys`: List of annotation keys to exclude from output
217  (supports wildcards with \*)
218- `include_annotation_keys`: List of annotation keys to include in output (if
219  specified, only these are included)
220 
221##### Annotation Filtering
222 
223The `list_resources` tool provides powerful annotation filtering capabilities to
224control metadata output size and prevent truncation issues with large
225annotations (such as GPU node annotations).
226 
227**Basic Usage:**
228 
229```json
230{
231  "name": "list_resources",
232  "arguments": {
233    "resource_type": "namespaced",
234    "group": "apps",
235    "version": "v1",
236    "resource": "deployments",
237    "namespace": "default"
238  }
239}
240```
241 
242**Exclude specific annotations (useful for GPU nodes):**
243 
244```json
245{
246  "name": "list_resources",
247  "arguments": {
248    "resource_type": "clustered",
249    "group": "",
250    "version": "v1",
251    "resource": "nodes",
252    "exclude_annotation_keys": [
253      "nvidia.com/*",
254      "kubectl.kubernetes.io/last-applied-configuration"
255    ]
256  }
257}
258```
259 
260**Include only specific annotations:**
261 
262```json
263{
264  "name": "list_resources",
265  "arguments": {
266    "resource_type": "namespaced",
267    "group": "",
268    "version": "v1",
269    "resource": "pods",
270    "namespace": "default",
271    "include_annotation_keys": ["app", "version", "prometheus.io/scrape"]
272  }
273}
274```
275 
276**Disable annotations completely for maximum performance:**
277 
278```json
279{
280  "name": "list_resources",
281  "arguments": {
282    "resource_type": "namespaced",
283    "group": "",
284    "version": "v1",
285    "resource": "pods",
286    "namespace": "default",
287    "include_annotations": false
288  }
289}
290```
291 
292**Annotation Filtering Rules:**
293 
294- By default, `kubectl.kubernetes.io/last-applied-configuration` is excluded to
295  prevent large configuration data
296- `exclude_annotation_keys` supports wildcard patterns using `*` (e.g.,
297  `nvidia.com/*` excludes all NVIDIA annotations)
298- When `include_annotation_keys` is specified, it takes precedence and only
299  those annotations are included
300- Setting `include_annotations: false` completely removes all annotations from
301  the output
302- Wildcard patterns only support `*` at the end of the key (e.g.,
303  `nvidia.com/*`)
304 
305#### apply_resource
306 
307Applies (creates or updates) a Kubernetes resource.
308 
309Parameters:
310 
311- `resource_type` (required): Type of resource to apply (clustered or
312  namespaced)
313- `group`: API group (e.g., apps, networking.k8s.io)
314- `version` (required): API version (e.g., v1, v1beta1)
315- `resource` (required): Resource name (e.g., deployments, services)
316- `namespace`: Namespace (required for namespaced resources)
317- `manifest` (required): Resource manifest
318 
319Example:
320 
321```json
322{
323  "name": "apply_resource",
324  "arguments": {
325    "resource_type": "namespaced",
326    "group": "apps",
327    "version": "v1",
328    "resource": "deployments",
329    "namespace": "default",
330    "manifest": {
331      "apiVersion": "apps/v1",
332      "kind": "Deployment",
333      "metadata": {
334        "name": "nginx-deployment",
335        "namespace": "default"
336      },
337      "spec": {
338        "replicas": 3,
339        "selector": {
340          "matchLabels": {
341            "app": "nginx"
342          }
343        },
344        "template": {
345          "metadata": {
346            "labels": {
347              "app": "nginx"
348            }
349          },
350          "spec": {
351            "containers": [
352              {
353                "name": "nginx",
354                "image": "nginx:latest",
355                "ports": [
356                  {
357                    "containerPort": 80
358                  }
359                ]
360              }
361            ]
362          }
363        }
364      }
365    }
366  }
367}
368```
369 
370#### post_resource
371 
372Posts to a Kubernetes resource or its subresource, particularly useful for
373executing commands in pods.
374 
375Parameters:
376 
377- `resource_type` (required): Type of resource to post to (clustered or
378  namespaced)
379- `group`: API group (e.g., apps, networking.k8s.io)
380- `version` (required): API version (e.g., v1, v1beta1)
381- `resource` (required): Resource name (e.g., deployments, services)
382- `namespace`: Namespace (required for namespaced resources)
383- `name` (required): Name of the resource to post to
384- `subresource`: Subresource to post to (e.g., exec)
385- `body` (required): Body to post to the resource
386- `parameters`: Optional parameters for the request
387 
388Example of executing a command in a pod:
389 
390```json
391{
392  "name": "post_resource",
393  "arguments": {
394    "resource_type": "namespaced",
395    "group": "",
396    "version": "v1",
397    "resource": "pods",
398    "namespace": "default",
399    "name": "my-pod",
400    "subresource": "exec",
401    "body": {
402      "command": ["ls", "-la", "/"],
403      "container": "my-container",
404      "timeout": 30
405    }
406  }
407}
408```
409 
410The `body` for pod exec supports the following fields:
411 
412- `command` (required): Command to execute, either as a string or an array of
413  strings
414- `container` (optional): Container name to execute the command in (defaults to
415  the first container)
416- `timeout` (optional): Timeout in seconds (defaults to 15 seconds, maximum 60
417  seconds)
418 
419Note on timeouts:
420 
421- Default timeout: 15 seconds if not specified
422- Maximum timeout: 60 seconds (any larger value will be capped)
423- Commands that exceed the timeout will be terminated and return a timeout error
424 
425The response includes stdout, stderr, and any error message:
426 
427```json
428{
429  "apiVersion": "v1",
430  "kind": "Pod",
431  "metadata": {
432    "name": "my-pod",
433    "namespace": "default"
434  },
435  "spec": {
436    "command": ["ls", "-la", "/"]
437  },
438  "status": {
439    "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...",
440    "stderr": "",
441    "error": ""
442  }
443}
444```
445 
446### MCP Resources
447 
448The MKP server provides access to Kubernetes resources through MCP resources.
449The resource URIs follow these formats:
450 
451- Clustered resources: `k8s://clustered/{group}/{version}/{resource}/{name}`
452- Namespaced resources:
453  `k8s://namespaced/{namespace}/{group}/{version}/{resource}/{name}`
454 
455### Configuration
456 
457#### Transport Protocol
458 
459MKP supports two transport protocols for the MCP server:
460 
461- **Streamable HTTP**: The default transport protocol, suitable for most use cases
462- **SSE (Server-Sent Events)**: Legacy transport protocol, primarily for compatibility with older clients
463 
464You can configure the transport protocol using either a CLI flag or an
465environment variable:
466 
467```bash
468# Using CLI flag
469./build/mkp-server --transport=sse
470 
471# Using environment variable
472MCP_TRANSPORT=sse ./build/mkp-server
473 
474# Default (Streamable HTTP)
475./build/mkp-server
476```
477 
478The `MCP_TRANSPORT` environment variable is automatically set by ToolHive when
479running MKP in that environment.
480 
481#### Controlling Resource Discovery
482 
483By default, MKP serves all Kubernetes resources as MCP resources, which provides
484useful context for LLMs. However, in large clusters with many resources, this
485can consume significant context space in the LLM.
486 
487You can disable this behavior by using the `--serve-resources` flag:
488 
489```bash
490# Run without serving cluster resources
491./build/mkp-server --serve-resources=false
492 
493# Run with a specific kubeconfig without serving cluster resources
494./build/mkp-server --kubeconfig=/path/to/kubeconfig --serve-resources=false
495```
496 
497Even with resource discovery disabled, the MCP tools (`get_resource`,
498`list_resources`, `apply_resource`, `delete_resource`, and `post_resource`)
499remain fully functional, allowing you to interact with your Kubernetes cluster.
500 
501#### Enabling Write Operations
502 
503By default, MKP operates in read-only mode, meaning it does not allow write
504operations on the cluster, i.e. the `apply_resource`, `delete_resource`, and
505`post_resource` tools will not be available. You can enable write operations by
506using the `--read-write` flag:
507 
508```bash
509# Run with write operations enabled
510./build/mkp-server --read-write=true
511 
512# Run with a specific kubeconfig and write operations enabled
513./build/mkp-server --kubeconfig=/path/to/kubeconfig --read-write=true
514```
515 
516### Rate Limiting
517 
518MKP includes a built-in rate limiting mechanism to protect the server from
519excessive API calls, which is particularly important when used with AI agents.
520The rate limiter uses a token bucket algorithm and applies different limits
521based on the operation type:
522 
523- Read operations (list_resources, get_resource): 120 requests per minute
524- Write operations (apply_resource, delete_resource): 30 requests per minute
525- Default for other operations: 60 requests per minute
526 
527Rate limits are applied per client session, ensuring fair resource allocation
528across multiple clients. The rate limiting feature can be enabled or disabled
529via the command line flag:
530 
531```bash
532# Run with rate limiting enabled (default)
533./build/mkp-server
534 
535# Run with rate limiting disabled
536./build/mkp-server --enable-rate-limiting=false
537```
538 
539Rate limits can be customized via environment variables:
540 
541- `MKP_RATE_LIMIT_DEFAULT`: Default rate limit (default: 60)
542- `MKP_RATE_LIMIT_READ`: Read operations rate limit (default: 120)
543- `MKP_RATE_LIMIT_WRITE`: Write operations rate limit (default: 30)
544 
545```bash
546# Run with custom rate limits
547MKP_RATE_LIMIT_READ=200 MKP_RATE_LIMIT_WRITE=50 ./build/mkp-server
548```
549 
550## Development
551 
552### Running tests
553 
554```bash
555task test
556```
557 
558### Formatting code
559 
560```bash
561task fmt
562```
563 
564### Linting code
565 
566```bash
567task lint
568```
569 
570### Updating dependencies
571 
572```bash
573task deps
574```
575 
576## Contributing
577 
578We welcome contributions to this MCP server! If you'd like to contribute, please
579review the [CONTRIBUTING guide](./CONTRIBUTING.md) for details on how to get
580started.
581 
582If you run into a bug or have a feature request, please
583[open an issue](https://github.com/StacklokLabs/mkp/issues) in the repository or
584join us in the `#mcp-servers` channel on our
585[community Discord server](https://discord.gg/stacklok).
586 
587## License
588 
589This project is licensed under the Apache v2 License - see the LICENSE file for
590details.
591