{"id":27702079,"url":"https://github.com/stackloklabs/mkp","last_synced_at":"2025-04-25T20:40:37.799Z","repository":{"id":289476131,"uuid":"971383139","full_name":"StacklokLabs/mkp","owner":"StacklokLabs","description":"KP is a Model Context Protocol (MCP) server for Kubernetes","archived":false,"fork":false,"pushed_at":"2025-04-23T13:49:12.000Z","size":89,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-23T13:59:54.224Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StacklokLabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-23T12:47:32.000Z","updated_at":"2025-04-23T13:49:16.000Z","dependencies_parsed_at":"2025-04-23T13:59:57.080Z","dependency_job_id":"041c041a-bcb5-4d63-a53b-0430eee9ef2d","html_url":"https://github.com/StacklokLabs/mkp","commit_stats":null,"previous_names":["stackloklabs/mkp"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StacklokLabs%2Fmkp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StacklokLabs%2Fmkp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StacklokLabs%2Fmkp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StacklokLabs%2Fmkp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StacklokLabs","download_url":"https://codeload.github.com/StacklokLabs/mkp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250894451,"owners_count":21504145,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-25T20:40:37.138Z","updated_at":"2025-04-25T20:40:37.779Z","avatar_url":"https://github.com/StacklokLabs.png","language":"Go","funding_links":[],"categories":["Cloud Platforms"],"sub_categories":[],"readme":"# MKP - Model Kontext Protocol Server for Kubernetes\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/mkp-logo.png\" width=\"400\" alt=\"MKP Logo\"\u003e\n\u003c/p\u003e\n\nMKP 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.\n\n## Features\n\n- List resources supported by the Kubernetes API server\n- List clustered resources\n- List namespaced resources\n- Get resources and their subresources (including status, scale, logs, etc.)\n- Apply (create or update) clustered resources\n- Apply (create or update) namespaced resources\n- Generic and pluggable implementation using API Machinery's unstructured client\n\n## Why MKP?\n\nMKP offers several key advantages as a Model Context Protocol server for Kubernetes:\n\n### Native Go Implementation\n- Built with the same language as Kubernetes itself\n- Excellent performance characteristics for server applications\n- Strong type safety and concurrency support\n- Seamless integration with Kubernetes libraries\n\n### Direct API Integration\n- Uses Kubernetes API machinery directly without external dependencies\n- No reliance on kubectl, helm, or other CLI tools\n- Communicates directly with the Kubernetes API server\n- Reduced overhead and improved reliability\n\n### Universal Resource Support\n- Works with any Kubernetes resource type through the unstructured client\n- No hardcoded resource schemas or specialized handlers needed\n- Automatically supports Custom Resource Definitions (CRDs)\n- Future-proof for new Kubernetes resources\n\n### Minimalist Design\n- Focused on core Kubernetes resource operations\n- Clean, maintainable codebase with clear separation of concerns\n- Lightweight with minimal dependencies\n- Easy to understand, extend, and contribute to\n\n### Production-Ready Architecture\n- Designed for reliability and performance in production environments\n- Proper error handling and resource management\n- Testable design with comprehensive unit tests\n- Follows Kubernetes development best practices\n\n## Prerequisites\n\n- Go 1.24 or later\n- Kubernetes cluster and kubeconfig\n- [Task](https://taskfile.dev/) for running tasks\n\n## Installation\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/StacklokLabs/mkp.git\ncd mkp\n```\n\n2. Install dependencies:\n\n```bash\ntask install\n```\n\n3. Build the server:\n\n```bash\ntask build\n```\n\n## Usage\n\n### Running the server\n\nTo run the server with the default kubeconfig:\n\n```bash\ntask run\n```\n\nTo run the server with a specific kubeconfig:\n\n```bash\nKUBECONFIG=/path/to/kubeconfig task run-with-kubeconfig\n```\n\n### MCP Tools\n\nThe MKP server provides the following MCP tools:\n\n#### get_resource\n\nGet a Kubernetes resource or its subresource.\n\nParameters:\n- `resource_type` (required): Type of resource to get (clustered or namespaced)\n- `group`: API group (e.g., apps, networking.k8s.io)\n- `version` (required): API version (e.g., v1, v1beta1)\n- `resource` (required): Resource name (e.g., deployments, services)\n- `namespace`: Namespace (required for namespaced resources)\n- `name` (required): Name of the resource to get\n- `subresource`: Subresource to get (e.g., status, scale, logs)\n- `parameters`: Optional parameters for the request (see examples below)\n\nExample:\n\n```json\n{\n  \"name\": \"get_resource\",\n  \"arguments\": {\n    \"resource_type\": \"namespaced\",\n    \"group\": \"apps\",\n    \"version\": \"v1\",\n    \"resource\": \"deployments\",\n    \"namespace\": \"default\",\n    \"name\": \"nginx-deployment\",\n    \"subresource\": \"status\"\n  }\n}\n```\n\nExample of getting logs from a specific container with parameters:\n\n```json\n{\n  \"name\": \"get_resource\",\n  \"arguments\": {\n    \"resource_type\": \"namespaced\",\n    \"group\": \"\",\n    \"version\": \"v1\",\n    \"resource\": \"pods\",\n    \"namespace\": \"default\",\n    \"name\": \"my-pod\",\n    \"subresource\": \"logs\",\n    \"parameters\": {\n      \"container\": \"my-container\",\n      \"sinceSeconds\": \"3600\",\n      \"timestamps\": \"true\",\n      \"limitBytes\": \"102400\"\n    }\n  }\n}\n```\n\nAvailable parameters for pod logs:\n- `container`: Specify which container to get logs from\n- `previous`: Get logs from previous container instance (true/false)\n- `sinceSeconds`: Only return logs newer than a relative duration in seconds\n- `sinceTime`: Only return logs after a specific time (RFC3339 format)\n- `timestamps`: Include timestamps on each line (true/false)\n- `limitBytes`: Maximum number of bytes to return\n- `tailLines`: Number of lines to return from the end of the logs\n\nBy 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.\n\nAvailable parameters for regular resources:\n- `resourceVersion`: When specified, shows the resource at that particular version\n\n#### list_resources\n\nLists Kubernetes resources of a specific type.\n\nParameters:\n- `resource_type` (required): Type of resource to list (clustered or namespaced)\n- `group`: API group (e.g., apps, networking.k8s.io)\n- `version` (required): API version (e.g., v1, v1beta1)\n- `resource` (required): Resource name (e.g., deployments, services)\n- `namespace`: Namespace (required for namespaced resources)\n\nExample:\n\n```json\n{\n  \"name\": \"list_resources\",\n  \"arguments\": {\n    \"resource_type\": \"namespaced\",\n    \"group\": \"apps\",\n    \"version\": \"v1\",\n    \"resource\": \"deployments\",\n    \"namespace\": \"default\"\n  }\n}\n```\n\n#### apply_resource\n\nApplies (creates or updates) a Kubernetes resource.\n\nParameters:\n- `resource_type` (required): Type of resource to apply (clustered or namespaced)\n- `group`: API group (e.g., apps, networking.k8s.io)\n- `version` (required): API version (e.g., v1, v1beta1)\n- `resource` (required): Resource name (e.g., deployments, services)\n- `namespace`: Namespace (required for namespaced resources)\n- `manifest` (required): Resource manifest\n\nExample:\n\n```json\n{\n  \"name\": \"apply_resource\",\n  \"arguments\": {\n    \"resource_type\": \"namespaced\",\n    \"group\": \"apps\",\n    \"version\": \"v1\",\n    \"resource\": \"deployments\",\n    \"namespace\": \"default\",\n    \"manifest\": {\n      \"apiVersion\": \"apps/v1\",\n      \"kind\": \"Deployment\",\n      \"metadata\": {\n        \"name\": \"nginx-deployment\",\n        \"namespace\": \"default\"\n      },\n      \"spec\": {\n        \"replicas\": 3,\n        \"selector\": {\n          \"matchLabels\": {\n            \"app\": \"nginx\"\n          }\n        },\n        \"template\": {\n          \"metadata\": {\n            \"labels\": {\n              \"app\": \"nginx\"\n            }\n          },\n          \"spec\": {\n            \"containers\": [\n              {\n                \"name\": \"nginx\",\n                \"image\": \"nginx:latest\",\n                \"ports\": [\n                  {\n                    \"containerPort\": 80\n                  }\n                ]\n              }\n            ]\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n### MCP Resources\n\nThe MKP server provides access to Kubernetes resources through MCP resources. The resource URIs follow these formats:\n\n- Clustered resources: `k8s://clustered/{group}/{version}/{resource}/{name}`\n- Namespaced resources: `k8s://namespaced/{namespace}/{group}/{version}/{resource}/{name}`\n\n### Controlling Resource Discovery\n\nBy default, MKP serves all Kubernetes resources as MCP resources, which provides useful context for LLMs. However, in large clusters with many resources, this can consume significant context space in the LLM.\n\nYou can disable this behavior by using the `--serve-resources` flag:\n\n```bash\n# Run without serving cluster resources\n./build/mkp-server --serve-resources=false\n\n# Run with a specific kubeconfig without serving cluster resources\n./build/mkp-server --kubeconfig=/path/to/kubeconfig --serve-resources=false\n```\n\nEven with resource discovery disabled, the MCP tools (`get_resource`, `list_resources`, and `apply_resource`) remain fully functional, allowing you to interact with your Kubernetes cluster.\n\n## Development\n\n### Running tests\n\n```bash\ntask test\n```\n\n### Formatting code\n\n```bash\ntask fmt\n```\n\n### Linting code\n\n```bash\ntask lint\n```\n\n### Updating dependencies\n\n```bash\ntask deps\n```\n\n## Running as an MCP Server with ToolHive\n\nMKP can be run as a Model Context Protocol (MCP) server using [ToolHive](https://github.com/StacklokLabs/toolhive), which simplifies the deployment and management of MCP servers.\n\n### Prerequisites\n\n1. Install ToolHive by following the [installation instructions](https://github.com/StacklokLabs/toolhive#installation).\n2. Ensure you have Docker or Podman installed on your system.\n3. Configure your Kubernetes credentials (kubeconfig) for the cluster you want to interact with.\n\n### Running MKP with ToolHive\n\nTo run MKP as an MCP server using ToolHive:\n\n```bash\n# Run the MKP server using the published container image\nthv run --name mkp --transport sse --target-port 8080 --volume $HOME/.kube:/home/nonroot/.kube:ro ghcr.io/stackloklabs/mkp/server:latest\n```\n\nThis command:\n- Names the server instance \"mkp\"\n- Uses the SSE transport protocol\n- Mounts your local kubeconfig into the container (read-only)\n- Uses the latest published MKP image from GitHub Container Registry\n\nTo use a specific version instead of the latest:\n\n```bash\nthv run --name mkp --transport sse --target-port 8080 --volume $HOME/.kube:/home/nonroot/.kube:ro ghcr.io/stackloklabs/mkp/server:v0.0.1\n```\n\n### Verifying the MKP Server is Running\n\nTo verify that the MKP server is running:\n\n```bash\nthv list\n```\n\nThis will show all running MCP servers managed by ToolHive, including the MKP server.\n\n### Stopping the MKP Server\n\nTo stop the MKP server:\n\n```bash\nthv stop mkp\n```\n\nTo remove the server instance completely:\n\n```bash\nthv rm mkp\n```\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackloklabs%2Fmkp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackloklabs%2Fmkp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackloklabs%2Fmkp/lists"}