Provides a comprehensive interface for managing Kubernetes clusters, including resource discovery, listing, detailed inspection, log retrieval, metrics collection, event tracking, and resource creation through a standardized MCP protocol.
Supports creation of Kubernetes resources from YAML manifests, enabling deployment of complex resources through the createorUpdateResource tool.
Kubernetes MCP Server
A Kubernetes Model Context Protocol (MCP) server that provides tools for interacting with Kubernetes clusters through a standardized interface.
Features
- API Resource Discovery: Get all available API resources in your Kubernetes cluster.
- Resource Listing: List resources of any type with optional namespace and label filtering.
- Resource Details: Get detailed information about specific Kubernetes resources.
- Resource Description: Get comprehensive descriptions of Kubernetes resources, similar to
kubectl describe
. - Pod Logs: Retrieve logs from specific pods (optionally from a specific container, or all containers if unspecified).
- Node Metrics: Get resource usage metrics for specific nodes.
- Pod Metrics: Get CPU and Memory metrics for specific pods.
- Event Listing: List events within a namespace or for a specific resource.
- Resource Creation/Updating: Create new Kubernetes resources or update existing ones from a YAML or JSON manifest.
- Standardized Interface: Uses the MCP protocol for consistent tool interaction.
- Flexible Configuration: Supports different Kubernetes contexts and resource scopes.
- Multiple Modes: Run in
stdio
mode for CLI tools orsse
mode for web applications.
Prerequisites
- Go 1.20 or later
- Access to a Kubernetes cluster
kubectl
configured with appropriate cluster access
Installation
- Clone the repository:
- Install dependencies:
- Build the server:
Usage
Starting the Server
The server can run in two modes, configurable via command-line flags or environment variables.
Stdio Mode (for CLI integrations)
This mode uses standard input/output for communication.
Or using environment variables:
SSE Mode (for web applications)
This mode starts an HTTP server with Server-Sent Events support.
Default (port 8080):
Specify a port:
Or using environment variables:
If no mode is specified, it defaults to SSE on port 8080.
Using the Docker Image
You can also run the server using the pre-built Docker image from Docker Hub.
- Pull the image:You can replace
latest
with a specific version tag (e.g.,1.0.0
). - Run the container:
- SSE Mode (default behavior of the image):This maps port 8080 of the container to port 8080 on your host and mounts your Kubernetes config read-only. The server will be available at
http://localhost:8080
. The image defaults tosse
mode on port8080
. - Stdio Mode:The
-i
flag is important for interactive stdio communication.--rm
cleans up the container after exit. - Custom Port for SSE Mode:
- SSE Mode (default behavior of the image):
Using with Docker Compose
Create a docker-compose.yml
file:
Then start with:
To see logs: docker compose logs -f k8s-mcp-server
.
Making API Calls (SSE Mode)
Once the server is running in SSE mode, you can make JSON-RPC calls to its HTTP endpoint (e.g., /
or /rpc
depending on the mcp-go
library's SSE server implementation):
(Note: The exact endpoint for JSON-RPC over HTTP when using the SSE server might depend on the mcp-go
library version. If /
doesn't work, try /rpc
.)
Available Tools
1. getAPIResources
Retrieves all available API resources in the Kubernetes cluster.
Parameters:
includeNamespaceScoped
(boolean, optional): Whether to include namespace-scoped resources (defaults to true).includeClusterScoped
(boolean, optional): Whether to include cluster-scoped resources (defaults to true).
Example:
2. listResources
Lists all instances of a specific resource type.
Parameters:
Kind
(string, required): The kind of resource to list (e.g., "Pod", "Deployment").namespace
(string, optional): The namespace to list resources from. If omitted, lists across all namespaces for namespaced resources (subject to RBAC).labelSelector
(string, optional): Filter resources by label selector (e.g., "app=nginx,env=prod").
Example:
3. getResource
Retrieves detailed information about a specific resource.
Parameters:
kind
(string, required): The kind of resource to get (e.g., "Pod", "Deployment").name
(string, required): The name of the resource to get.namespace
(string, optional): The namespace of the resource (required for namespaced resources).
Example:
4. describeResource
Describes a resource in the Kubernetes cluster, similar to kubectl describe
.
Parameters:
Kind
(string, required): The kind of resource to describe (e.g., "Pod", "Deployment").name
(string, required): The name of the resource to describe.namespace
(string, optional): The namespace of the resource (required for namespaced resources).
Example:
5. getPodsLogs
Retrieves the logs of a specific pod.
Parameters:
Name
(string, required): The name of the pod.namespace
(string, required): The namespace of the pod.containerName
(string, optional): The specific container name within the pod. If omitted:- If the pod has one container, its logs are fetched.
- If the pod has multiple containers, logs from all containers are fetched and concatenated.
Example:
6. getNodeMetrics
Retrieves resource usage metrics for a specific node.
Parameters:
Name
(string, required): The name of the node.
Example:
7. getPodMetrics
Retrieves CPU and Memory metrics for a specific pod.
Parameters:
namespace
(string, required): The namespace of the pod.podName
(string, required): The name of the pod.
Example:
8. getEvents
Retrieves events for a specific namespace or resource.
Parameters:
namespace
(string, optional): The namespace to get events from. If omitted, events from all namespaces are considered (subject to RBAC).resourceName
(string, optional): The name of a specific resource (e.g., a Pod name) to filter events for.resourceKind
(string, optional): The kind of the specific resource (e.g., "Pod") ifresourceName
is provided.
Example (Namespace Events):
Example (Resource Events):
9. createOrUpdateResource
Creates a new resource or updates an existing one from a YAML or JSON manifest.
Parameters:
manifest
(string, required): The YAML or JSON manifest of the resource.namespace
(string, optional): The namespace in which to create/update the resource. If the manifest contains a namespace, this parameter can be used to override it. If not provided and the manifest doesn't specify one, "default" might be assumed or it might be an error depending on the resource type.
Example:
Development
Project Structure
Adding New Tools
- Define the Tool: In
tools/tools.go
, define a function that returns anmcp.Tool
structure. This includes the tool's name, description, and input/output schemas. - Implement the Handler: In
handlers/handlers.go
, create a handler function. This function takes*k8s.Client
as an argument and returns a function with the signaturefunc(context.Context, mcp.ToolInput) (mcp.ToolOutput, error)
. This inner function will contain the logic for your tool. - Register the Tool: In
main.go
, add your new tool to the MCP server instance usings.AddTool(tools.YourToolDefinitionFunction(), handlers.YourToolHandlerFunction(client))
.
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for details on how to contribute to this project.
License
This project is licensed under the MIT License - see the LICENSE file for details.
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A Kubernetes Model Context Protocol (MCP) server that provides tools for interacting with Kubernetes clusters through a standardized interface.
Related MCP Servers
- AsecurityAlicenseAqualityA beginner-friendly Model Context Protocol (MCP) server that helps users understand MCP concepts, provides interactive examples, and lists available MCP servers. This server is designed to be a helpful companion for developers working with MCP. Also comes with a huge list of servers you can install.Last updated -3936JavaScriptApache 2.0
- -securityAlicense-qualityMCP Server simplifies the implementation of the Model Context Protocol by providing a user-friendly API to create custom tools and manage server workflows efficiently.Last updated -43TypeScriptMIT License
- -securityAlicense-qualityMCP Server provides a simpler API to interact with the Model Context Protocol by allowing users to define custom tools and services to streamline workflows and processes.Last updated -132TypeScriptMIT License
- -securityAlicense-qualityA Model Context Protocol (MCP) server designed to easily dump your codebase context into Large Language Models (LLMs).Last updated -21JavaScriptApache 2.0