Adding first set of user documentation

README.md

@@ -54,6 +54,15 @@ If you're using the native binaries you don't need to have Node or Python instal
 
 - Access to a Kubernetes cluster.
 
+<details>
+<summary><b>Claude Code</b></summary>
+
+Follow the [dedicated Claude Code getting started guide](docs/GETTING_STARTED_CLAUDE_CODE.md) in our [user documentation](docs/).
+
+For a secure production setup with dedicated ServiceAccount and read-only access, also review the [Kubernetes setup guide](docs/GETTING_STARTED_KUBERNETES.md).
+
+</details>
+
 ### Claude Desktop
 
 #### Using npx

docs/GETTING_STARTED_CLAUDE_CODE.md

@@ -0,0 +1,99 @@
+# Using Kubernetes MCP Server with Claude Code CLI
+
+This guide shows you how to configure the Kubernetes MCP Server with Claude Code CLI.
+
+> **Prerequisites:** Complete the [Getting Started with Kubernetes](GETTING_STARTED_KUBERNETES.md) guide first to create a ServiceAccount and kubeconfig file.
+
+## Quick Setup
+
+Add the MCP server using the `claude mcp add-json` command:
+
+```bash
+claude mcp add-json kubernetes-mcp-server \
+  '{"command":"npx","args":["-y","kubernetes-mcp-server@latest","--read-only"],"env":{"KUBECONFIG":"'${HOME}'/.kube/mcp-viewer.kubeconfig"}}' \
+  -s user
+```
+
+**What this does:**
+- Adds the Kubernetes MCP Server to your Claude Code configuration
+- Uses `npx` to automatically download and run the latest version
+- Enables read-only mode for safety
+- Uses the kubeconfig file you created in the Getting Started guide
+- `-s user` makes it available in all your projects
+
+## Manual Configuration (Alternative)
+
+If you prefer to edit the config file manually:
+
+**Location:** `~/.config/claude-code/config.toml`
+
+```toml
+[[mcp_servers]]
+name = "kubernetes-mcp-server"
+command = "npx"
+args = [
+    "-y",
+    "kubernetes-mcp-server@latest",
+    "--read-only"
+]
+
+[mcp_servers.env]
+KUBECONFIG = "/home/YOUR_USERNAME/.kube/mcp-viewer.kubeconfig"
+```
+
+**Important:** Replace `/home/YOUR_USERNAME/` with your actual home directory path.
+
+## Verify Connection
+
+After adding the MCP server, verify it's connected:
+
+```bash
+claude mcp list
+```
+
+Expected output:
+```
+Checking MCP server health...
+
+kubernetes-mcp-server: npx -y kubernetes-mcp-server@latest --read-only - ✓ Connected
+```
+
+## Using the MCP Server
+
+Once connected, interact with your Kubernetes cluster using natural language! Claude will use the Kubernetes MCP Server
+to fetch and display the relevant information from your cluster:
+
+```bash
+> List all namespaces in my cluster 
+
+● I'll list all the namespaces in your Kubernetes cluster.
+  ⎿  APIVERSION   KIND        NAME                 STATUS   AGE   LABELS
+     v1           Namespace   default              Active   77m   kubernetes.io/metadata.name=default
+     v1           Namespace   kube-node-lease      Active   77m   kubernetes.io/metadata.name=kube-node-lease
+     … +4 lines (ctrl+o to expand)
+
+● Your cluster has 6 namespaces:
+
+  1. default - The default namespace for resources without a specified namespace
+  2. kube-node-lease - Used for node heartbeat/lease objects
+  3. kube-public - Publicly accessible namespace, typically for cluster information
+  4. kube-system - System namespace for Kubernetes control plane components
+  5. local-path-storage - Likely used for local storage provisioning
+  6. mcp - Custom namespace (created ~75 minutes ago)
+
+  All namespaces are in Active status and the cluster appears to be running for about 77 minutes.
+```
+
+## Configuration Options
+
+Common command-line flags you can add to the `args` array:
+
+| Flag | Description |
+|------|-------------|
+| `--read-only` | Enable read-only mode (recommended) |
+| `--kubeconfig <path>` | Path to kubeconfig file (or use `KUBECONFIG` env var) |
+
+## Next Steps
+
+- Review the [Getting Started with Kubernetes](GETTING_STARTED_KUBERNETES.md) guide for more details on ServiceAccount setup
+- Explore the [main README](../README.md) for more MCP server capabilities

docs/GETTING_STARTED_KUBERNETES.md

@@ -0,0 +1,242 @@
+# Getting Started with Kubernetes MCP Server
+
+This guide walks you through the foundational setup for using the Kubernetes MCP Server with your Kubernetes cluster. You'll create a dedicated, read-only ServiceAccount and generate a secure kubeconfig file that can be used with various MCP clients.
+
+> **Note:** This setup is **recommended for production use** but not strictly required. The MCP Server can use your existing kubeconfig file (e.g., `~/.kube/config`), but using a dedicated ServiceAccount with limited permissions follows the principle of least privilege and is more secure.
+
+> **Next:** After completing this guide, continue with the [Claude Code CLI guide](GETTING_STARTED_CLAUDE_CODE.md). See the [docs README](README.md) for all available guides.
+
+## What You'll Create
+
+By the end of this guide, you'll have:
+- A dedicated `mcp-viewer` ServiceAccount with read-only cluster access
+- A secure, time-bound authentication token
+- A dedicated kubeconfig file (`~/.kube/mcp-viewer.kubeconfig`)
+
+## Prerequisites
+
+- A running Kubernetes cluster
+- `kubectl` CLI installed and configured
+- Cluster admin permissions to create ServiceAccounts and RBAC bindings
+
+## 1. Create a Read-Only ServiceAccount and RBAC
+
+A ServiceAccount represents a non-human identity. Binding it to a read-only role lets tools query the cluster safely without using administrator credentials.
+
+### Step 1.1: Create the Namespace and ServiceAccount
+
+First, create a Namespace for the ServiceAccount:
+
+```bash
+# Create or pick a Namespace for the ServiceAccount
+kubectl create namespace mcp
+
+# Create the ServiceAccount
+kubectl create serviceaccount mcp-viewer -n mcp
+```
+
+### Step 1.2: Grant Read-Only Access (RBAC)
+
+Use a ClusterRoleBinding or RoleBinding to grant read-only permissions.
+
+#### Option A: Cluster-Wide Read-Only (Most Common)
+
+This binds the ServiceAccount to the built-in `view` ClusterRole, which provides read-only access across the whole cluster.
+
+```bash
+# Binds the view ClusterRole to the ServiceAccount
+kubectl create clusterrolebinding mcp-viewer-crb \
+    --clusterrole=view \
+    --serviceaccount=mcp:mcp-viewer
+```
+
+#### Option B: Namespace-Scoped Only (Tighter Scope)
+
+This limits read access to the `mcp` namespace only, using the built-in `view` Role.
+
+```bash
+# Binds the view role to the ServiceAccount within the 'mcp' namespace
+kubectl create rolebinding mcp-viewer-rb \
+    --role=view \
+    --serviceaccount=mcp:mcp-viewer \
+    -n mcp
+```
+
+### Quick Verification (Optional)
+
+Verify the permissions granted to the ServiceAccount:
+
+```bash
+# Check if the ServiceAccount can list pods cluster-wide
+# Expect 'yes' if you used the view ClusterRole (Option A)
+kubectl auth can-i list pods --as=system:serviceaccount:mcp:mcp-viewer --all-namespaces
+```
+
+## 2. Mint a ServiceAccount Token
+
+Tools authenticate via a bearer token. We use the TokenRequest API (`kubectl create token`) to generate a secure, short-lived token.
+
+```bash
+# Create a time-bound token (choose a duration, e.g., 2 hours)
+TOKEN="$(kubectl create token mcp-viewer --duration=2h -n mcp)"
+
+# Verify the token was generated (Optional)
+echo "$TOKEN"
+```
+
+**Note:** The `kubectl create token` command requires Kubernetes v1.24+. For older versions, you'll need to extract the token from the ServiceAccount's secret.
+
+## 3. Build a Dedicated Kubeconfig
+
+A dedicated kubeconfig file isolates this ServiceAccount's credentials from your personal admin credentials, making it easy to point external tools at.
+
+### Step 3.1: Get Cluster Details
+
+Get the API server address and certificate authority from your current active context:
+
+```bash
+# 1. Get the current cluster API server address
+API_SERVER="$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')"
+
+# 2. Get the cluster's Certificate Authority (CA) file path or data
+# First, try to get the CA file path
+CA_FILE="$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.certificate-authority}')"
+
+# If CA file is not set, extract the CA data and write it to a temp file
+if [ -z "$CA_FILE" ]; then
+    CA_FILE="/tmp/k8s-ca-$$.crt"
+    kubectl config view --minify --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > "$CA_FILE"
+fi
+
+# 3. Define the desired context name
+CONTEXT_NAME="mcp-viewer-context"
+KUBECONFIG_FILE="$HOME/.kube/mcp-viewer.kubeconfig"
+```
+
+### Step 3.2: Create and Configure the Kubeconfig File
+
+Create the new kubeconfig file by defining the cluster, user (the ServiceAccount), and context:
+
+```bash
+# Create a new kubeconfig file with cluster configuration
+kubectl config --kubeconfig="$KUBECONFIG_FILE" set-cluster mcp-viewer-cluster \
+    --server="$API_SERVER" \
+    --certificate-authority="$CA_FILE" \
+    --embed-certs=true
+
+# Set the ServiceAccount token as the user credential
+kubectl config --kubeconfig="$KUBECONFIG_FILE" set-credentials mcp-viewer \
+    --token="$TOKEN"
+
+# Define the context (links the cluster and user)
+kubectl config --kubeconfig="$KUBECONFIG_FILE" set-context "$CONTEXT_NAME" \
+    --cluster=mcp-viewer-cluster \
+    --user=mcp-viewer
+
+# Set the new context as current
+kubectl config --kubeconfig="$KUBECONFIG_FILE" use-context "$CONTEXT_NAME"
+
+# Secure the file permissions
+chmod 600 "$KUBECONFIG_FILE"
+
+# Clean up temporary CA file if we created one
+if [[ "$CA_FILE" == /tmp/k8s-ca-*.crt ]]; then
+    rm -f "$CA_FILE"
+fi
+```
+
+### Quick Sanity Check
+
+You can now use this new file to verify access:
+
+```bash
+# Run a command using the dedicated kubeconfig file
+kubectl --kubeconfig="$KUBECONFIG_FILE" get pods -A
+```
+
+This command should successfully list all Pods if you chose **Option A: Cluster-Wide Read-Only**, proving the ServiceAccount and its token are correctly configured.
+
+## 4. Use with Kubernetes MCP Server
+
+Now that you have a dedicated kubeconfig file, you can use it with the Kubernetes MCP Server:
+
+```bash
+# Run the MCP server with the dedicated kubeconfig
+./kubernetes-mcp-server --kubeconfig="$HOME/.kube/mcp-viewer.kubeconfig"
+
+# Or use npx
+npx -y kubernetes-mcp-server@latest --kubeconfig="$HOME/.kube/mcp-viewer.kubeconfig"
+
+# Or use uvx
+uvx kubernetes-mcp-server@latest --kubeconfig="$HOME/.kube/mcp-viewer.kubeconfig"
+```
+
+Alternatively, you can set the `KUBECONFIG` environment variable:
+
+```bash
+export KUBECONFIG="$HOME/.kube/mcp-viewer.kubeconfig"
+./kubernetes-mcp-server
+```
+
+## Token Expiration and Renewal
+
+The token created in Step 2 has a limited lifetime (2 hours in the example). When it expires, you'll need to:
+
+1. Generate a new token:
+   ```bash
+   TOKEN="$(kubectl create token mcp-viewer --duration=2h -n mcp)"
+   ```
+
+2. Update the kubeconfig file:
+   ```bash
+   kubectl config --kubeconfig="$KUBECONFIG_FILE" set-credentials mcp-viewer --token="$TOKEN"
+   ```
+
+For long-running applications, consider:
+- Using a longer token duration (up to the cluster's maximum, typically 24h)
+- Implementing automatic token renewal in your application
+- Using a different authentication method (e.g., client certificates)
+
+## Cleanup
+
+To remove the ServiceAccount and associated RBAC bindings:
+
+```bash
+# Delete the ClusterRoleBinding (if using Option A)
+kubectl delete clusterrolebinding mcp-viewer-crb
+
+# Delete the RoleBinding (if using Option B)
+kubectl delete rolebinding mcp-viewer-rb -n mcp
+
+# Delete the ServiceAccount
+kubectl delete serviceaccount mcp-viewer -n mcp
+
+# Delete the namespace (optional - only if you created it specifically for this)
+kubectl delete namespace mcp
+
+# Remove the kubeconfig file
+rm "$HOME/.kube/mcp-viewer.kubeconfig"
+```
+
+## Troubleshooting
+
+### kubectl create token: command not found
+
+This command requires Kubernetes v1.24+. For older versions, you'll need to extract the token from the ServiceAccount's secret manually.
+
+### Permission denied errors
+
+Ensure you're using the correct kubeconfig file and that the ServiceAccount has the necessary RBAC permissions. Verify with:
+
+```bash
+kubectl auth can-i list pods --as=system:serviceaccount:mcp:mcp-viewer --all-namespaces
+```
+
+## Next Steps
+
+Now that you have a working kubeconfig with read-only access, configure Claude Code CLI:
+
+- **[Using with Claude Code CLI](GETTING_STARTED_CLAUDE_CODE.md)** - Configure the MCP server with Claude Code CLI
+
+You can also:
+- Explore the [main README](../README.md) for more MCP server capabilities

docs/README.md

@@ -0,0 +1,21 @@
+# Kubernetes MCP Server Documentation
+
+Welcome to the Kubernetes MCP Server documentation! This directory contains guides to help you set up and use the Kubernetes MCP Server with your Kubernetes cluster and Claude Code CLI.
+
+## Getting Started Guides
+
+Choose the guide that matches your needs:
+
+| Guide | Description | Best For |
+|-------|-------------|----------|
+| **[Getting Started with Kubernetes](GETTING_STARTED_KUBERNETES.md)** | Base setup: Create ServiceAccount, token, and kubeconfig | Everyone - **start here first** |
+| **[Using with Claude Code CLI](GETTING_STARTED_CLAUDE_CODE.md)** | Configure MCP server with Claude Code CLI | Claude Code CLI users |
+
+## Recommended Workflow
+
+1. **Complete the base setup**: Start with [Getting Started with Kubernetes](GETTING_STARTED_KUBERNETES.md) to create a ServiceAccount and kubeconfig file
+2. **Configure Claude Code**: Then follow the [Claude Code CLI guide](GETTING_STARTED_CLAUDE_CODE.md)
+
+## Additional Documentation
+
+- **[Main README](../README.md)** - Project overview and general information