# Kubectl Mcp Server

> MCP Server (STDIO) for kubectl CLI operations

- **Type:** MCP server
- **Install:** `agentstack add mcp-aadarshjain-kubectl-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aadarshjain](https://agentstack.voostack.com/s/aadarshjain)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aadarshjain](https://github.com/aadarshjain)
- **Source:** https://github.com/aadarshjain/kubectl-mcp-server

## Install

```sh
agentstack add mcp-aadarshjain-kubectl-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Kubectl MCP Server

A Model Context Protocol (MCP) server for Kubernetes cluster management and information gathering using kubectl commands and the Kubernetes Python client.

## Table of Contents

- [Overview](#overview)
- [Project Structure](#project-structure)
- [Features](#features)
- [Installation](#installation)
  - [Prerequisites](#prerequisites)
  - [Setup](#setup)
- [Running the Server](#running-the-server)
  - [Basic Usage](#basic-usage)
- [Available Tools](#available-tools)
- [Configuration](#configuration)
  - [Kubeconfig Setup](#kubeconfig-setup)
  - [Claude Desktop Configuration](#claude-desktop-configuration)
- [Security](#security)
- [Example Usage](#example-usage)
- [Troubleshooting](#troubleshooting)

## Overview

This MCP server provides a seamless interface between LLMs (like Claude) and Kubernetes clusters. It enables natural language interactions with your Kubernetes resources without manually running kubectl commands or writing complex API calls. The server supports both read-only operations for safe information gathering and full kubectl command execution when needed.

## Project Structure

```
kubectl-mcp-server/
├── README.md                  # Project documentation
├── requirements.txt           # Python dependencies
├── .env                       # Environment configuration file (create from .env.example)
├── .env.example               # Example environment configuration
└── server.py                  # Main server application with FastMCP setup
```

## Features

- **Cluster Management**: List and switch between different Kubernetes contexts
- **Read-only Operations**: Safe kubectl commands for information gathering (get, describe, explain)
- **Full kubectl Support**: Execute any kubectl command when needed
- **Kubernetes API Integration**: Direct access to Kubernetes APIs through Python client
- **Context Switching**: Seamlessly switch between different cluster contexts
- **Safety Controls**: Built-in protection against destructive operations in read-only mode

## Installation

### Prerequisites

For local development and testing, you'll need:

#### System Requirements
- **Python 3.8+** - The MCP server is built with Python
- **kubectl** - Kubernetes command-line tool installed and configured
- **Kubernetes cluster access** - Valid kubeconfig with cluster credentials

#### Optional (for Claude Desktop integration)
- **Claude Desktop** application installed
- **Node.js and npm** (if using npx for mcp-remote)

### Setup

1. Clone and navigate to the project:
   ```bash
   git clone 
   cd kubectl-mcp-server
   ```

2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

3. Configure environment variables:
   ```bash
   cp .env.example .env
   # Edit .env file to set your kubeconfig path if different from default
   ```

4. Ensure kubectl is installed and configured:
   ```bash
   kubectl version --client
   kubectl config get-contexts
   ```

## Running the Server

### Basic Usage

```bash
# Run with defaults
python server.py

# Run with debug logging
python server.py --log-level debug
```

## Available Tools

### 1. `list_clusters()`
Lists all available Kubernetes clusters from your kubeconfig file.

**Returns:**
- List of available clusters with names and cluster information
- Currently active context

**Example:**
```json
{
  "clusters": [
    {"name": "prod-cluster", "cluster": "prod-k8s"},
    {"name": "dev-cluster", "cluster": "dev-k8s"}
  ],
  "active_context": "prod-cluster"
}
```

### 2. `get_current_context()`
Gets the current Kubernetes context being used by both the MCP server and the system.

**Returns:**
- Current context stored in MCP server
- System's current kubectl context

**Example:**
```json
{
  "current_context": "prod-cluster",
  "system_context": "prod-cluster"
}
```

### 3. `switch_context(context: str)`
Switches to a different Kubernetes context.

**Parameters:**
- `context` (string): Name of the context to switch to

**Returns:**
- Success message or error details

**Example:**
```python
switch_context("dev-cluster")
# Returns: {"message": "Switched to context: dev-cluster"}
```

### 4. `run_kubectl_command_ro(command: str)`
Executes read-only kubectl commands safely.

**Parameters:**
- `command` (string): kubectl command starting with "kubectl"

**Allowed Operations:**
- `get` - Retrieve resources
- `describe` - Show detailed resource information
- `explain` - Show resource documentation
- `config view` - View kubeconfig
- `config get-contexts` - List available contexts
- `version` - Show kubectl/cluster version
- `api-resources` - List available API resources
- `cluster-info` - Show cluster information

**Returns:**
- Command output or error message

**Example:**
```bash
run_kubectl_command_ro("kubectl get pods -n default")
```

### 5. `run_kubectl_command(command: str)`
Executes any kubectl command (use with caution).

**Parameters:**
- `command` (string): kubectl command starting with "kubectl"

**Returns:**
- Command output or error message

**Warning:** This tool can execute destructive operations. Use `run_kubectl_command_ro()` for safe information gathering.

## Configuration

### Environment Variables

The server uses environment variables for configuration, which can be set in a `.env` file:

```bash
# Path to the kubeconfig file
# Use full path for reliability, e.g., /Users/yourusername/.kube/config
# If not set, defaults to ~/.kube/config
KUBECONFIG_PATH=/Users/yourusername/.kube/config

# Log level for the server
LOG_LEVEL=INFO
```

### Kubeconfig Setup

Ensure your kubeconfig is properly configured:

```bash
# Check current context
kubectl config current-context

# List all contexts
kubectl config get-contexts

# Set default context
kubectl config use-context 
```

The server will automatically load from:
1. The path specified in `KUBECONFIG_PATH` environment variable
2. The `KUBECONFIG` environment variable
3. Default location (`~/.kube/config`)

### Claude Desktop Configuration

To integrate with Claude Desktop, add this configuration to your Claude Desktop config file:

```json
{
  "mcpServers": {
    "kubectl-mcp-server": {
      "command": "/full/path/to/python",
      "args": ["/path/to/kubectl-mcp-server/server.py"]
    }
  }
}
```

Config file locations:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

## Security

### Read-only Mode
The `run_kubectl_command_ro()` tool provides safe access by:
- Allowing only information-gathering commands
- Blocking destructive operations (delete, update, patch, etc.)
- Preventing resource modifications

### Access Control
- Server inherits permissions from your kubeconfig
- No additional authentication layer (relies on Kubernetes RBAC)
- Commands execute with the same privileges as your kubectl setup

### Best Practices
- Use `run_kubectl_command_ro()` for general queries
- Reserve `run_kubectl_command()` for trusted operations only
- Regularly audit your kubeconfig permissions
- Consider using dedicated service accounts with limited permissions

## Example Usage

### Basic Cluster Information
```
User: What clusters do I have access to?
Claude: [Uses list_clusters() to show available contexts]

User: Switch to the development cluster
Claude: [Uses switch_context("dev-cluster")]

User: Show me all pods in the default namespace
Claude: [Uses run_kubectl_command_ro("kubectl get pods -n default")]
```

### Resource Inspection
```
User: Describe the nginx deployment
Claude: [Uses run_kubectl_command_ro("kubectl describe deployment nginx")]

User: What's the current cluster version?
Claude: [Uses run_kubectl_command_ro("kubectl version")]

User: Show me all namespaces
Claude: [Uses run_kubectl_command_ro("kubectl get namespaces")]
```

### Advanced Operations
```
User: Scale the nginx deployment to 3 replicas
Claude: [Uses run_kubectl_command("kubectl scale deployment nginx --replicas=3")]
```

## Troubleshooting

### Common Issues

**Connection Problems:**
- Verify kubectl connectivity: `kubectl cluster-info`
- Check kubeconfig: `kubectl config view`
- Ensure proper authentication to your clusters

**Permission Errors:**
- Check RBAC permissions in your cluster
- Verify service account has necessary permissions
- Review kubeconfig user credentials

**Context Switching Issues:**
- List available contexts: `kubectl config get-contexts`
- Verify context names match exactly
- Check if context exists in kubeconfig

**Import Errors:**
- Install required dependencies: `pip install -r requirements.txt`
- Verify Python version compatibility (3.8+)
- Check kubectl installation: `kubectl version --client`

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aadarshjain](https://github.com/aadarshjain)
- **Source:** [aadarshjain/kubectl-mcp-server](https://github.com/aadarshjain/kubectl-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-aadarshjain-kubectl-mcp-server
- Seller: https://agentstack.voostack.com/s/aadarshjain
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.