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:
- There are tools that mimic the output of kubectl commands (e.g.
get_pod_summaries, which is equivalent tokubectl get pods). Strongly-typed Pydantic models are used for the return values of these tools. - 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. - 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 isdict[str,Any], but we document the fields in the function's docstring.get_pod_specis 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, likekubectl get namespaceget_node_summaries- get a list of nodes, likekubectl get nodes -o wideget_pod_summaries- get a list of pods, likekubectl get pods -o wideget_pod_container_statuses- return the status for each of the container in a podget_pod_events- return the events for a podget_pod_spec- retrieves the spec for a given podget_logs_for_pod_and_container- retrieves logs from a pod and containerget_deployment_summaries- get a list of deployments, likekubectl get deploymentsget_service_summaries- get a list of services, likekubectl get services
We also define a set of associated "print_" functions that are helpful in debugging:
print_namespacesprint_node_summariesprint_pod_summariesprint_pod_container_statusesprint_pod_eventsprint_pod_specprint_deployment_summariesprint_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:
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 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:
- The Python virtual environment is expected to be in
.venvunder the root of your VSCode workspace - You have installed the k8stools package into your workspace
- The environment file
.envrccontains any variables you need defined. In particular, you may need to setKUBECONFIGto point to yourkubectlconfig 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 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 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 viaTool.from_function()inmcp_server.pyWhen answering questions about the user's kubernetes cluster, use the tools provided by this server, which is configured in
mcp.jsonask8stools-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.