Kubernetes Tools MCP Server

Kubernetes Tools

This package provides a collection of Kubernetes functions to be used by Agents. They can be passed directly to an agent as tools or placed behind an MCP server (included). Some use cases include:

• Chat with your kubernetes cluster via GitHub CoPilot or Cursor.
• Build agents to monitor your cluster or perform root cause analysis.
• Vibe-code a custom chat UI.
• Use in non-agentic automations.

Methodology

Our goal is to focus on quality over quantity -- providing well-documented and strongly typed tools. We believe that this is a critical in enabling agents to make effective use of tools, beyond simple demos.

These are built on top of the kubernetes Python API (https://github.com/kubernetes-client/python). There are three styles of tools provided here:

1. There are tools that mimic the output of kubectl commands (e.g. get_pod_summaries, which is equivalent to kubectl get pods). Strongly-typed Pydantic models are used for the return values of these tools.
2. There are tools that return strongly typed Pydantic models that attempt to match the associated Kubernetes client types (see https://github.com/kubernetes-client/python/tree/master/kubernetes/docs). Lesser used fields may be omitted from these models. An example of this case is get_pod_container_statuses.
3. In some cases we simply call to_dict() on the class returned by the API (defined in https://github.com/kubernetes-client/python/tree/master/kubernetes/client/models). The return type is dict[str,Any], but we document the fields in the function's docstring. get_pod_spec is an example of this type of tool.

Currently, the priority is on functions that do not modify the state of the cluster. We want to focus first on the monitoring / RCA use cases. When we do add tools to address other use cases, they will be kept separate from the read-only tools so you can still build "safe" agents.

Installation

Via pip:

Via uv:

Current tools

These are the tools we define:

• get_namespaces - get a list of namespaces, like kubectl get namespace
• get_node_summaries - get a list of nodes, like kubectl get nodes -o wide
• get_pod_summaries - get a list of pods, like kubectl get pods -o wide
• get_pod_container_statuses - return the status for each of the container in a pod
• get_pod_events - return the events for a pod
• get_pod_spec - retrieves the spec for a given pod
• get_logs_for_pod_and_container - retrieves logs from a pod and container
• get_deployment_summaries - get a list of deployments, like kubectl get deployments
• get_service_summaries - get a list of services, like kubectl get services

We also define a set of associated "print_" functions that are helpful in debugging:

• print_namespaces
• print_node_summaries
• print_pod_summaries
• print_pod_container_statuses
• print_pod_events
• print_pod_spec
• print_deployment_summaries
• print_service_summaries

Using the tools

Directly use in an agent

The core tools are in k8stools.k8s_tools. Here's an example usage in an agent:

Using via MCP

The script k8s-mcp-server provides an MCP server for the same set of tools. Here are the command line arguments for the server:

Use MCP with the stdio transport

The stdio transport is best for use with local Coding Agents, like GitHub CoPilot or Cursor. It is the default, so you can run the k8s-mcp-server script without arguments. Here's an example mcp.json configuration:

This assumes the following:

1. The Python virtual environment is expected to be in .venv under the root of your VSCode workspace
2. You have installed the k8stools package into your workspace
3. The environment file .envrc contains any variables you need defined. In particular, you may need to set KUBECONFIG to point to your kubectl config file.

Use MCP with the streamable HTTP transport

The streamable http transport is enabled with the command line option --transport=streamable-http. It will start an HTTP server which listens on the specified address and port (defaulting to 127.0.0.1 and 8000, respectively). This transport is best for cases where you want remote access to your MCP server.

Here's a short example that starts the server and then does a sanity test using curl to get the tool information:

Mock tools

When building agents, it can be helpful to test them against mock versions that do not go against a real cluster, but return static (but realistic) values. The module k8stools.mock_tools does just that. The data values were captured when running against a real Minikube instance running the Open Telemetry Demo application. When running the MCP server, this may be enabled by using the --mock command line option.

Instruction files

GitHub CoPilot supports instruction files that can provide additional context to the CoPilot Coding Agent. It can even analyze your project and create one for you. By default, this gets saved to .github/copilot-instructions.md. You can manually add instructions to customize your agent for using your MCP tools. As an example, here's the additional content included in this repository's copilot-instructions.md:

MCP Integration

Run server: k8s-mcp-server [--transport stdio|streamable-http] Tools auto-registered via Tool.from_function() in mcp_server.py

When answering questions about the user's kubernetes cluster, use the tools provided by this server, which is configured in mcp.json as k8stools-stdio. Some other considerations when answering these questions:

• If the answer includes multiple, similar entries, format as a table if possible.
• When providing pod statuses, be sure to include the state of the pod.
• When providing a status, use an icon show quickly show if it is good or bad.
• If you are asked for the current status, and you haven't run a request in more than an minute, be sure to run the tool again to get the latest status.