# kubectl-mcp-app
[](https://www.npmjs.com/package/kubectl-mcp-app)
[](https://opensource.org/licenses/MIT)
Interactive UI add-on for kubectl-mcp-server using the MCP ext-apps SDK.
## Overview
kubectl-mcp-app provides 8 interactive UI dashboards for Kubernetes management that integrate seamlessly with Claude Desktop through the Model Context Protocol (MCP).
## Features
| Tool | Description |
| ---- | ----------- |
| `k8s-pods` | Interactive pod viewer with filtering, sorting, status indicators, and actions |
| `k8s-logs` | Real-time log viewer with syntax highlighting, search, and level filtering |
| `k8s-deploy` | Deployment dashboard with rollout status, scaling, restart, and rollback |
| `k8s-helm` | Helm release manager with upgrade, rollback, and uninstall actions |
| `k8s-cluster` | Cluster overview with node status, resource allocation, and health metrics |
| `k8s-cost` | Cost analyzer with waste detection and right-sizing recommendations |
| `k8s-events` | Events timeline with type filtering and resource grouping |
| `k8s-network` | Network topology graph showing Services, Pods, and Ingress connections |
## Prerequisites
- **Node.js** >= 18.0.0
- **kubectl-mcp-server** >= 1.21.0 (automatically spawned or connect to existing)
- **kubectl** configured with access to your Kubernetes cluster
- **Claude Desktop** (for MCP integration)
## Installation
### Via npm
```bash
npm install -g kubectl-mcp-app
```
### Via npx (no installation required)
```bash
npx kubectl-mcp-app
```
### From source
```bash
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server/kubectl-mcp-app
npm install
npm run build
npm link
```
## Quick Start
### 1. Configure Claude Desktop
Add to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"kubectl-app": {
"command": "npx",
"args": ["kubectl-mcp-app"]
}
}
}
```
### 2. Restart Claude Desktop
After updating the configuration, restart Claude Desktop to load the new MCP server.
### 3. Use the Tools
Ask Claude to use any of the Kubernetes UI tools:
- "Show me my pods using the k8s-pods UI"
- "Open the deployment dashboard"
- "Analyze my cluster costs"
- "Show the network topology for the default namespace"
## Configuration Modes
### Mode 1: Standalone (Default)
Spawns kubectl-mcp-server as a subprocess automatically.
```json
{
"mcpServers": {
"kubectl-app": {
"command": "npx",
"args": ["kubectl-mcp-app"]
}
}
}
```
### Mode 2: With Specific Context
Use a specific Kubernetes context:
```json
{
"mcpServers": {
"kubectl-app": {
"command": "npx",
"args": ["kubectl-mcp-app", "--context", "production-cluster"]
}
}
}
```
### Mode 3: Connect to Existing Server
Connect to an already-running kubectl-mcp-server:
```json
{
"mcpServers": {
"kubectl": {
"command": "kubectl-mcp-server",
"args": ["serve", "--transport", "streamable-http", "--port", "8000"]
},
"kubectl-app": {
"command": "npx",
"args": ["kubectl-mcp-app", "--backend", "http://localhost:8000/mcp"]
}
}
}
```
## CLI Options
```text
kubectl-mcp-app [OPTIONS]
OPTIONS:
-b, --backend <URL> Connect to remote kubectl-mcp-server backend
-c, --context <NAME> Kubernetes context to use
-n, --namespace <NAME> Default namespace
-h, --help Show help message
-v, --version Show version
EXAMPLES:
kubectl-mcp-app # Start with defaults
kubectl-mcp-app --context prod # Use specific context
kubectl-mcp-app --backend http://host:8000 # Connect to remote server
```
## Architecture
```text
┌─────────────────────────────────────────────────────────────────────┐
│ MCP Host (Claude Desktop) │
├─────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ kubectl-mcp-app │────▶│ Interactive UI (iframe) │ │
│ │ (TypeScript) │ │ - Pod Viewer │ │
│ │ │ │ - Log Viewer │ │
│ │ Tools: │ │ - Deployment Dashboard │ │
│ │ - k8s-pods │ │ - Helm Manager │ │
│ │ - k8s-logs │ │ - Cluster Overview │ │
│ │ - k8s-deploy │ │ - Cost Analyzer │ │
│ │ - k8s-helm │ │ - Events Timeline │ │
│ │ - k8s-cluster │ │ - Network Topology │ │
│ │ - k8s-cost │ └─────────────────────────────────────┘ │
│ │ - k8s-events │ │ │
│ │ - k8s-network │ │ callServerTool() │
│ └────────┬────────┘ │ │
│ │ ▼ │
│ │ ┌─────────────────────────────────────┐ │
│ └─────────────▶│ kubectl-mcp-server │ │
│ MCP proxy │ (Python, 270+ tools) │ │
│ │ stdio/SSE/HTTP │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```
## UI Features
### Pod Viewer (`k8s-pods`)
- Interactive table with sorting and filtering
- Status indicators (Running, Pending, Failed, CrashLoopBackOff, etc.)
- CPU/Memory usage progress bars
- Quick actions: View logs, Delete pod
- Namespace selector
- Search across all columns
### Log Viewer (`k8s-logs`)
- Real-time log streaming with auto-scroll
- Syntax highlighting for JSON and timestamps
- Regex search support
- Filter by log level (INFO, WARN, ERROR, DEBUG)
- Multi-container selector
- Download logs as file
### Deployment Dashboard (`k8s-deploy`)
- Replica count visualization with progress bars
- Rolling update status tracking
- Quick actions: Scale, Restart, Rollback
- Revision history
- Strategy information (RollingUpdate/Recreate)
### Helm Manager (`k8s-helm`)
- Release table with status badges
- Version and revision tracking
- Chart and app version display
- Actions: Upgrade, Rollback, Uninstall
- Release details modal
### Cluster Overview (`k8s-cluster`)
- Node health donut chart
- Pod count and namespace count
- Kubernetes version display
- Resource allocation (CPU/Memory) charts
- Node cards with status and resource usage
### Cost Analyzer (`k8s-cost`)
- Resource waste detection by namespace
- Right-sizing recommendations with confidence levels
- Potential savings calculator
- CPU/Memory usage vs requests charts
- Apply recommendations button
### Events Timeline (`k8s-events`)
- Vertical timeline visualization
- Event type filtering (Normal/Warning)
- Resource grouping by date
- Click-to-expand event details
- Auto-refresh toggle
### Network Topology (`k8s-network`)
- Force-directed graph visualization
- Shows Services, Pods, and Ingress
- Connection lines with port information
- Click to inspect node details
- Pan and zoom controls
- Legend for resource types
## Development
### Setup
```bash
# Clone the repository
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server/kubectl-mcp-app
# Install dependencies
npm install
# Build everything
npm run build
```
### Commands
```bash
# Build UI components (all 8 UIs)
npm run build:ui
# Build server (TypeScript → JavaScript)
npm run build:server
# Build everything
npm run build
# Development mode with hot reload
npm run dev
# Type checking
npm run typecheck
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
```
### Project Structure
```text
kubectl-mcp-app/
├── src/
│ ├── server.ts # MCP server with tool/resource registration
│ ├── main.ts # CLI entry point
│ ├── proxy.ts # Proxy to kubectl-mcp-server
│ ├── types.ts # Shared TypeScript types
│ └── ui/ # UI components
│ ├── shared/ # Shared components and utilities
│ │ ├── components/ # Table, StatusBadge, Chart, etc.
│ │ ├── theme.ts # Dark/light theme support
│ │ └── k8s-client.ts
│ ├── pods/
│ ├── logs/
│ ├── deployments/
│ ├── helm/
│ ├── cluster/
│ ├── cost/
│ ├── events/
│ └── network/
├── test/ # Test files
├── dist/ # Build output
│ ├── server.js
│ ├── main.js
│ └── ui/ # Bundled single-file HTML apps
├── scripts/ # Build scripts
├── package.json
├── tsconfig.json
├── tsconfig.server.json
└── vite.config.ts
```
## Troubleshooting
### "kubectl-mcp-server not found"
Install kubectl-mcp-server:
```bash
pip install kubectl-mcp-server
```
Or use the `--backend` option to connect to a remote server.
### "No pods found"
Ensure kubectl is configured correctly:
```bash
kubectl get pods
```
### UI not loading
Check that the dist/ui/ directory contains the HTML files:
```bash
ls dist/ui/
```
If empty, rebuild the UIs:
```bash
npm run build:ui
```
### Connection timeout
If connecting to a remote backend, ensure:
1. The server is running and accessible
2. The URL includes the `/mcp` path
3. No firewall is blocking the connection
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md) for development guidelines.
## License
MIT - see [LICENSE](./LICENSE) for details.
## Related Projects
- [kubectl-mcp-server](https://github.com/rohitg00/kubectl-mcp-server) - MCP server for Kubernetes with 270+ tools
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
- [Claude Desktop](https://claude.ai/download) - Desktop app for Claude with MCP support
