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:

pip install k8stools

Via uv:

uv add k8stools

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 (includes capacity/allocatable/conditions/taints/labels)
• 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 (supports tail, since_seconds, and previous)
• get_deployment_summaries - get a list of deployments, like kubectl get deployments
• get_replicaset_summaries - get a deployment's replica sets with their revision numbers and images. A deployment's replica sets are its change history: use this to see when a workload last changed and what the change was.
• get_service_summaries - get a list of services, like kubectl get services (includes selector/labels/annotations)
• get_configmap_summaries - get a list of ConfigMaps, like kubectl get configmaps
• get_configmap - retrieve the full contents of a single ConfigMap
• get_statefulset_summaries - get a list of StatefulSets, like kubectl get statefulsets
• get_cronjob_summaries - get a list of CronJobs, like kubectl get cronjobs
• get_job_summaries - get a list of Jobs, like kubectl get jobs
• get_logs_for_job - retrieve logs from a Job's most-recent pod
• get_logs_for_cronjob - retrieve logs from a CronJob's most-recent run
• get_pvc_summaries - get a list of PersistentVolumeClaims, like kubectl get pvc (resolves mounting pods)
• get_events - list cluster/namespace-wide events with server-side filtering

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
• print_configmap_summaries
• print_configmap
• print_statefulset_summaries
• print_cronjob_summaries
• print_job_summaries
• print_pvc_summaries
• print_events

Using the tools

Directly use in an agent

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

from pydantic_ai.agent import Agent
from k8stools.k8s_tools import TOOLS

agent = Agent(
        model="openai:gpt-4.1",
        system_prompt=SYSTEM_PROMPT,
        tools=TOOLS
)

result = agent.run_sync("What is the status of the pods in my cluster?")
print(result.output)

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:

usage: k8s-mcp-server [-h] [--transport {streamable-http,stdio}] [--host HOST] [--port PORT]
                      [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--debug] [--mock]
                      [--no-redact]

Run the MCP server.

options:
  -h, --help            show this help message and exit
  --transport {streamable-http,stdio}
                        Transport to use for MCP server [default: stdio]
  --host HOST           Hostname for HTTP service [default: 127.0.0.1]
  --port PORT           Port for HTTP service [default: 8000]
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Log level [default: INFO]
  --debug               Enable debug mode [default: False]
  --mock                Run mock versions of the tools that don't need a cluster
  --no-redact           Disable secret redaction of tool output (on by default)

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:

{
   "servers": {
      "k8stools-stdio": {
         "command": "${workspaceFolder}/.venv/bin/k8s-mcp-server",
         "args": [
         ],
         "envFile": "${workspaceFolder}/.envrc"
      }
   }
}

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:

# start the server
 $ k8s-mcp-server --transport=streamable-http
[07/21/25 19:55:13] INFO     Starting with 18 tools on transport streamable-http          mcp_server.py:59
INFO:     Started server process [6649]
INFO:     Waiting for application startup.
INFO     StreamableHTTP session manager started         streamable_http_manager.py:111
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

# Now, open another terminal window and test it
$ curl -v \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{
           "jsonrpc": "2.0",
           "id": 1,
           "method": "tools/list",
           "params": {}
         }' \
     http://127.0.0.1:8000/mcp
*   Trying 127.0.0.1:8000...
* Connected to 127.0.0.1 (127.0.0.1) port 8000
> POST /mcp HTTP/1.1
> Host: 127.0.0.1:8000
> User-Agent: curl/8.7.1
> Content-Type: application/json
> Accept: application/json, text/event-stream
> Content-Length: 120
>
* upload completely sent off: 120 bytes
< HTTP/1.1 200 OK
< date: Tue, 22 Jul 2025 02:56:25 GMT
< server: uvicorn
< cache-control: no-cache, no-transform
< connection: keep-alive
< content-type: text/event-stream
< x-accel-buffering: no
< Transfer-Encoding: chunked
<
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"tools":[.... long text elided ...]}}

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.

Secret redaction

Some read-only resources can carry secret-shaped values even though they are not Kubernetes Secret objects — ConfigMap data and the env blocks in a pod spec are the common cases. When you run the k8stools MCP server directly against an agent (with no wrapping service to scrub output), those values would otherwise flow straight into the model's context.

To prevent that, the MCP server applies a redaction pass to every tool's output. It is on by default and can be disabled with --no-redact or by setting K8STOOLS_REDACT=0. Redaction matches both by value shape (AWS access keys, JWT / bearer tokens, PEM private-key blocks) and by key / env-var name (key|secret|token|password|credential), replacing each match with a visible [REDACTED] marker so the agent can tell "hidden" from "absent". We never provide a reader for Kubernetes Secret objects.

If you call the tool functions directly in Python (rather than through the MCP server), you get raw, un-redacted values; you can apply the same pass yourself via k8stools.redaction.redact_object.