GoogleCloudPlatform/kubectl-ai is a developer-focused project on GitHub with 7.6k stars, written primarily in Go. AI powered Kubernetes Assistant
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
kubectl-ai acts as an intelligent interface, translating user intent into
precise Kubernetes operations, making Kubernetes management more accessible and
efficient.
Table of Contents
Quick Start
Installation
Usage
Configuration
Tools
Docker Quick Start
MCP Client Mode
Extras
MCP Server Mode
Start Contributing
Learning Resources
Quick Start
First, ensure that kubectl is installed and configured.
Download the latest release from the releases page for your target machine.
Untar the release, make the binary executable and move it to a directory in your $PATH (as shown below).
tar -zxvf kubectl-ai_Darwin_arm64.tar.gz
chmod a+x kubectl-ai
sudo mv kubectl-ai /usr/local/bin/
Install with Krew (Linux/macOS/Windows)
First of all, you need to have krew installed, refer to krew document for more details
Then you can install with krew
kubectl krew install ai
Now you can invoke kubectl-ai as a kubectl plugin like this: kubectl ai.
Install on NixOS
There are multiple ways to install kubectl-ai on NixOS. For a permanent installation add the following to your NixOS-Configuration:
environment.systemPackages = with pkgs; [
kubectl-ai
];
For a temporary installation, you can use the following command:
nix-shell -p kubectl-ai
Usage
kubectl-ai supports AI models from gemini, vertexai, azopenai, openai, grok, bedrock and local LLM providers such as ollama and llama.cpp.
Using Gemini (Default)
Set your Gemini API key as an environment variable. If you don't have a key, get one from Google AI Studio.
export GEMINI_API_KEY=your_api_key_here
kubectl-ai
# Use different gemini model
kubectl-ai --model gemini-2.5-pro-exp-03-25
# Use 2.5 flash (faster) model
kubectl-ai --quiet --model gemini-2.5-flash-preview-04-17 "check logs for nginx app in hello namespace"
Use other AI models
Using AI models running locally (ollama or llama.cpp)
You can use kubectl-ai with AI models running locally. kubectl-ai supports ollama and llama.cpp to use the AI models running locally.
Additionally, the modelserving directory provides tools and instructions for deploying your own llama.cpp-based LLM serving endpoints locally or on a Kubernetes cluster. This allows you to host models like Gemma directly in your environment.
An example of using Google's gemma3 model with ollama:
# assuming ollama is already running and you have pulled one of the gemma models
# ollama pull gemma3:12b-it-qat
# if your ollama server is at remote, use OLLAMA_HOST variable to specify the host
# export OLLAMA_HOST=http://192.168.1.3:11434/
# enable-tool-use-shim because models require special prompting to enable tool calling
kubectl-ai --llm-provider ollama --model gemma3:12b-it-qat --enable-tool-use-shim
# you can use `models` command to discover the locally available models
>> models
Using Grok
You can use X.AI's Grok model by setting your X.AI API key:
The interactive mode allows you to have a chat with kubectl-ai, asking multiple questions in sequence while maintaining context from previous interactions. Simply type your queries and press Enter to receive responses. To exit the interactive shell, type exit or press Ctrl+C.
Or, run with a task as input:
kubectl-ai --quiet "fetch logs for nginx app in hello namespace"
Combine it with other unix commands:
kubectl-ai < query.txt
# OR
echo "list pods in the default namespace" | kubectl-ai
You can even combine a positional argument with stdin input. The positional argument will be used as a prefix to the stdin content:
cat error.log | kubectl-ai "explain the error"
We also support persistence between runs with an opt-in. This lets you save a session to the local filesystem, and resume it to maintain previous context. It even works between different interfaces!
kubectl-ai --new-session # start a new session
kubectl-ai --list-sessions # list all saved sessions
kubectl-ai --resume-session 20250807-510872 # resume session 20250807-510872
kubectl-ai --delete-session 20250807-510872 # delete session 20250807-510872
Configuration
You can also configure kubectl-ai using a YAML configuration file at ~/.config/kubectl-ai/config.yaml:
Command line flags take precedence over configuration file settings.
Tools
kubectl-ai leverages LLMs to suggest and execute Kubernetes operations using a set of powerful tools. It comes with built-in tools like kubectl and bash.
You can also extend its capabilities by defining your own custom tools. By default, kubectl-ai looks for your tool configurations in ~/.config/kubectl-ai/tools.yaml.
To specify tools configuration files or directories containing tools configuration files, use:
Set up application default credentials and connect to your GKE cluster.
gcloud auth application-default login # If in a gcloud shell this is not necessary
gcloud container clusters get-credentials <cluster-name> --zone <zone>
Step 3: Run the kubectl-ai container
Below is a sample command that can be used to launch the container with a locally hosted web-ui. Be sure to replace the placeholder values with your specific Google Cloud project ID and location. Note you do not need to mount the gcloud config directory if you're on a cloudshell machine.
For more info about running from the container image see CONTAINER.md
MCP Client Mode
Note: MCP Client Mode is available in kubectl-ai version v0.0.12 and onwards.
kubectl-ai can connect to external MCP Servers to access additional tools in addition to built-in tools.
Quick Start with MCP Client
Enable MCP client mode:
kubectl-ai --mcp-client
MCP Client Configuration
Create or edit ~/.config/kubectl-ai/mcp.yaml to customize MCP servers:
servers:
# Local MCP server (stdio-based)
# sequential-thinking: Advanced reasoning and step-by-step analysis
- name: sequential-thinking
command: npx
args:
- -y
- "@modelcontextprotocol/server-sequential-thinking"
# Remote MCP server (HTTP-based)
- name: cloudflare-documentation
url: https://docs.mcp.cloudflare.com/mcp
# Optional: Remote MCP server with authentication
- name: custom-api
url: https://api.example.com/mcp
auth:
type: "bearer"
token: "${MCP_TOKEN}"
The system automatically:
Converts parameter names (snake_case → camelCase)
Handles type conversion (strings → numbers/booleans when appropriate)
Provides fallback behavior for unknown servers
No additional setup required - just use the --mcp-client flag and the AI will have access to all configured MCP tools.
📖 For detailed configuration options, troubleshooting, and advanced features for MCP Client mode, see the MCP Client Documentation.
📖 For multi-server orchestration and security automation examples, see the MCP Client Integration Guide.
Extras
You can use the following special keywords for specific actions:
model: Display the currently selected model.
models: List all available models.
tools: List all available tools.
version: Display the kubectl-ai version.
reset: Clear the conversational context.
clear: Clear the terminal screen.
exit or quit: Terminate the interactive shell (Ctrl+C also works).
Invoking as kubectl plugin
You can also run kubectl ai. kubectl finds any executable file in your PATH whose name begins with kubectl- as a plugin.
MCP Server Mode
kubectl-ai can act as an MCP server that exposes kubectl tools to other MCP clients (like Claude, Cursor, or VS Code). The server can run in two modes:
Basic MCP Server (Built-in tools only)
Expose only kubectl-ai's native Kubernetes tools:
kubectl-ai --mcp-server
Enhanced MCP Server (With external tool discovery)
Additionally discover and expose tools from other MCP servers as a unified interface:
kubectl-ai --mcp-server --external-tools
This creates a powerful tool aggregation hub where kubectl-ai acts as both:
MCP Server: Exposing kubectl tools to clients
MCP Client: Consuming tools from other MCP servers
To serve clients over HTTP using the streamable transport, run:
This starts an MCP endpoint at http://localhost:9080/mcp.
The enhanced mode provides AI clients with access to both Kubernetes operations and general-purpose tools (filesystem, web search, databases, etc.) through a single MCP endpoint.
Authenticating the HTTP Endpoint (OAuth 2.1)
The streamable-http endpoint is unauthenticated by default — anyone who can reach the port can run kubectl and bash. For non-localhost use, turn the server into an OAuth 2.1 Resource Server that requires a Bearer access token (verified locally against an authorization server's JWKS, e.g. AuthGate):
--mcp-auth-audience is this server's resource identifier; the JWT's aud claim must match it, which binds each token to this MCP server and prevents tokens issued for other services (same authorization server) from being replayed here. It is required once --mcp-auth-issuer is set — see Why the audience (aud) matters.
Authentication is opt-in: without --mcp-auth-issuer the endpoint behaves exactly as before. See the MCP Server Documentation for details.
📖 For detailed configuration, examples, and troubleshooting, see the MCP Server Documentation.
Start Contributing
We welcome contributions to kubectl-ai from the community. Take a look at our
contribution guide to get started.
Learning Resources
Talks and Presentations
From Natural Language to K8s Operations: The MCP Architecture and Practice of kubectl-ai - A comprehensive presentation covering the architecture and practical usage of kubectl-ai with MCP (Model Context Protocol).
Note: This is not an officially supported Google product. This project is not
eligible for the Google Open Source Software Vulnerability Rewards
Program.
Does GoogleCloudPlatform/kubectl-ai have a project website?
No homepage URL was recorded for GoogleCloudPlatform/kubectl-ai in TopGit's last sync. The README tab above frequently contains screenshots and demo links, or check the repository description on GitHub.
How active is development on GoogleCloudPlatform/kubectl-ai?
The most recent commit recorded on GoogleCloudPlatform/kubectl-ai was 4 months ago, based on the GitHub push timestamp. The repository has 724 forks — one of the better signals of community interest.
Is GoogleCloudPlatform/kubectl-ai open source?
Yes — GoogleCloudPlatform/kubectl-ai ships under the Apache-2.0 license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/GoogleCloudPlatform/kubectl-ai.
What license does GoogleCloudPlatform/kubectl-ai use?
GoogleCloudPlatform/kubectl-ai is released under the Apache-2.0 license. Always verify the LICENSE file directly on GitHub for the authoritative terms — license strings can be edited out of sync with a project's actual stance.
What topics is GoogleCloudPlatform/kubectl-ai associated with?
GitHub's repository topics for GoogleCloudPlatform/kubectl-ai: "ai", "assistant", "cli", "kubernetes". TopGit's editorial category is Developer Tools.
Where do I read more about GoogleCloudPlatform/kubectl-ai?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/GoogleCloudPlatform/kubectl-ai is the definitive source.
Read full README in the tab above.
Curious whether kubectl-ai is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about kubectl-ai.