K8stools

🚀 Kubernetes Tools

This package offers a collection of Kubernetes functions for Agents. These functions can either be directly passed to an agent as tools or deployed behind an MCP server (which is included). Here are some use cases:

• Chat with your Kubernetes cluster using GitHub CoPilot or Cursor.
• Build agents to monitor your cluster or conduct root cause analysis.
• Develop a custom chat UI with Vibe - code.
• Utilize in non - agentic automations.

✨ Features

Our objective is to prioritize quality over quantity, offering well - documented and strongly typed tools. We believe this is crucial for agents to effectively utilize tools beyond simple demos.

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

1. Tools that mimic the output of kubectl commands (e.g., get_pod_summaries, equivalent to kubectl get pods). Strongly - typed Pydantic models are used for their return values.
2. Tools that return strongly typed Pydantic models attempting 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 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], and we document the fields in the function's docstring. get_pod_spec is an example of this type of tool.

Currently, the focus is on functions that do not modify the cluster's state. We aim to first address monitoring / RCA use cases. When adding tools for other use cases, they will be separated from read - only tools, allowing you to build "safe" agents.

📦 Installation

Via pip

pip install k8stools

Via uv

uv add k8stools

💻 Usage Examples

Current Tools

Here are the tools we've defined:

• get_namespaces: Get a list of namespaces, similar to kubectl get namespace.
• get_node_summaries: Get a list of nodes, similar to kubectl get nodes -o wide.
• get_pod_summaries: Get a list of pods, similar to kubectl get pods -o wide.
• get_pod_container_statuses: Return the status of each container in a pod.
• get_pod_events: Return the events for a pod.
• get_pod_spec: Retrieve the spec for a given pod.
• get_logs_for_pod_and_container: Retrieve logs from a pod and container.
• get_deployment_summaries: Get a list of deployments, similar to kubectl get deployments.
• get_service_summaries: Get a list of services, similar to kubectl get services.

We also have a set of associated "print_" functions useful for 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

Direct Use in an Agent

The core tools are in k8stools.k8s_tools. Here's an example of using them 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]

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]

Use MCP with the stdio Transport

The stdio transport is ideal for local Coding Agents like GitHub CoPilot or Cursor. It's 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:

1. The Python virtual environment is in .venv under the root of your VSCode workspace.
2. You've installed the k8stools package in your workspace.
3. The environment file .envrc contains any necessary variables. 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 starts an HTTP server listening on the specified address and port (defaulting to 127.0.0.1 and 8000, respectively). This transport is best for remote access to your MCP server.

Here's a short example of starting the server and performing 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 6 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's useful to test them against mock versions that don't interact with a real cluster but return static (yet realistic) values. The module k8stools.mock_tools serves this purpose. The data values were captured when running against a real Minikube instance running the [Open Telemetry Demo](https://github.com/open - telemetry/opentelemetry - demo) application. When running the MCP server, you can enable this 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 is saved to .github/copilot - instructions.md. You can manually add instructions to customize your agent for using your MCP tools. Here's an example of the additional content 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. Consider the following when answering these questions:

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