Metadata-Version: 2.4
Name: kubectl-mcp-tool
Version: 1.0.0
Summary: A Model Context Protocol (MCP) server for Kubernetes
Home-page: https://github.com/rohitg00/kubectl-mcp-server
Author: Rohit Ghumare
Author-email: Rohit Ghumare <ghumare64@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/rohitg00/kubectl-mcp-server
Project-URL: Bug Tracker, https://github.com/rohitg00/kubectl-mcp-server/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.22.0
Requires-Dist: kubernetes>=28.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: aiohttp-sse>=2.1.0
Requires-Dist: PyYAML>=6.0.1
Requires-Dist: requests>=2.31.0
Requires-Dist: urllib3>=2.1.0
Requires-Dist: websocket-client>=1.7.0
Requires-Dist: jsonschema>=4.20.0
Requires-Dist: cryptography>=42.0.2
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Kubectl MCP Tool

A Model Context Protocol (MCP) server for Kubernetes that enables AI assistants like Claude, Cursor, and others to interact with Kubernetes clusters through natural language.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
[![Kubernetes](https://img.shields.io/badge/kubernetes-%23326ce5.svg?style=flat&logo=kubernetes&logoColor=white)](https://kubernetes.io/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://github.com/modelcontextprotocol/spec)

## Features

### Core Kubernetes Operations
- [x] Connect to a Kubernetes cluster
- [x] List and manage pods, services, deployments, and nodes
- [x] Create, delete, and describe pods and other resources
- [x] Get pod logs and Kubernetes events
- [x] Support for Helm v3 operations (installation, upgrades, uninstallation)
- [x] kubectl explain and api-resources support
- [x] Choose namespace for next commands (memory persistence)
- [x] Port forward to pods
- [x] Scale deployments and statefulsets
- [x] Execute commands in containers
- [x] Manage ConfigMaps and Secrets
- [x] Rollback deployments to previous versions
- [x] Ingress and NetworkPolicy management
- [x] Context switching between clusters

### Natural Language Processing
- [x] Process natural language queries for kubectl operations
- [x] Context-aware commands with memory of previous operations
- [x] Human-friendly explanations of Kubernetes concepts
- [x] Intelligent command construction from intent
- [x] Fallback to kubectl when specialized tools aren't available
- [x] Mock data support for offline/testing scenarios
- [x] Namespace-aware query handling

### Monitoring
- [x] Cluster health monitoring
- [x] Resource utilization tracking
- [x] Pod status and health checks
- [x] Event monitoring and alerting
- [x] Node capacity and allocation analysis
- [x] Historical performance tracking
- [x] Resource usage statistics via kubectl top
- [x] Container readiness and liveness tracking

### Security
- [x] RBAC validation and verification
- [x] Security context auditing
- [x] Secure connections to Kubernetes API
- [x] Credentials management
- [x] Network policy assessment
- [x] Container security scanning
- [x] Security best practices enforcement
- [x] Role and ClusterRole management
- [x] ServiceAccount creation and binding
- [x] PodSecurityPolicy analysis
- [x] RBAC permissions auditing
- [x] Security context validation

### Diagnostics
- [x] Cluster diagnostics and troubleshooting
- [x] Configuration validation
- [x] Error analysis and recovery suggestions
- [x] Connection status monitoring
- [x] Log analysis and pattern detection
- [x] Resource constraint identification
- [x] Pod health check diagnostics
- [x] Common error pattern identification
- [x] Resource validation for misconfigurations
- [x] Detailed liveness and readiness probe validation

### Advanced Features
- [x] Multiple transport protocols support (stdio, SSE)
- [x] Integration with multiple AI assistants
- [x] Extensible tool framework
- [x] Custom resource definition support
- [x] Cross-namespace operations
- [x] Batch operations on multiple resources
- [x] Intelligent resource relationship mapping
- [x] Error explanation with recovery suggestions
- [x] Volume management and identification

## Architecture

### Model Context Protocol (MCP) Integration

The Kubectl MCP Tool implements the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/spec), enabling AI assistants to interact with Kubernetes clusters through a standardized interface. The architecture consists of:

1. **MCP Server**: A compliant server that handles requests from MCP clients (AI assistants)
2. **Tools Registry**: Registers Kubernetes operations as MCP tools with schemas
3. **Transport Layer**: Supports stdio, SSE, and HTTP transport methods
4. **Core Operations**: Translates tool calls to Kubernetes API operations
5. **Response Formatter**: Converts Kubernetes responses to MCP-compliant responses

### Request Flow

![Request Flow](./image.png)

### Dual Mode Operation

The tool operates in two modes:

1. **CLI Mode**: Direct command-line interface for executing Kubernetes operations
2. **Server Mode**: Running as an MCP server to handle requests from AI assistants

## Installation

### Prerequisites

- Python 3.9+
- kubectl CLI installed and configured
- Access to a Kubernetes cluster
- pip (Python package manager)

### Global Installation

```bash
# Install latest version from PyPI
pip install kubectl-mcp-tool

# Or install development version from GitHub
pip install git+https://github.com/rohitg00/kubectl-mcp-server.git
```

### Local Development Installation

```bash
# Clone the repository
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server

# Install in development mode
pip install -e .
```

### Verifying Installation

After installation, verify the tool is working correctly:

```bash
# Check CLI mode
kubectl-mcp --help

# Test connection to Kubernetes
kubectl-mcp get pods
```

## Usage with AI Assistants

### Claude Desktop

Add the following to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "kubernetes": {
      "command": "python",
      "args": ["-m", "kubectl_mcp_tool.cli"]
    }
  }
}
```

### Cursor AI

Add the following to your Cursor AI configuration:

```json
{
  "tools": [
    {
      "name": "kubectl-mcp",
      "command": "python",
      "args": ["-m", "kubectl_mcp_tool.cli"],
      "description": "A tool for interacting with Kubernetes clusters."
    }
  ]
}
```

### Windsurf

Add the following to your Windsurf configuration:

```json
{
  "extensions": [
    {
      "name": "kubectl-mcp",
      "description": "Kubernetes operations using MCP",
      "exec": {
        "command": "python",
        "args": ["-m", "kubectl_mcp_tool.cli"]
      }
    }
  ]
}
```

## Prerequisites

1. kubectl installed and in your PATH
2. A valid kubeconfig file
3. Access to a Kubernetes cluster
4. Helm v3 (optional, for Helm operations)

## Examples

### List Pods

```
List all pods in the default namespace
```

### Deploy an Application

```
Create a deployment named nginx-test with 3 replicas using the nginx:latest image
```

### Check Pod Logs

```
Get logs from the nginx-test pod
```

### Port Forwarding

```
Forward local port 8080 to port 80 on the nginx-test pod
```

## Development

```bash
# Clone the repository
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

# Run tests
python -m python_tests.test_all_features
```

## Project Structure

```
├── kubectl_mcp_tool/         # Python implementation
│   ├── cli.py                # CLI entry point
│   ├── mcp_server.py         # MCP server implementation
│   ├── core/                 # Core functionality
│   ├── security/             # Security operations
│   └── monitoring/           # Monitoring functionality
├── python_tests/             # Python tests
├── compatible_servers/       # Compatible MCP server implementations
│   ├── cursor/               # Cursor-compatible servers
│   ├── windsurf/             # Windsurf-compatible servers
│   ├── minimal/              # Minimal server implementations
│   └── generic/              # Generic MCP servers
└── docs/                     # Documentation
    ├── cursor/               # Cursor integration docs
    ├── windsurf/             # Windsurf integration docs
    └── claude/               # Claude integration docs
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the LICENSE file for details.
