npm package: @iwaneo/kubernetes-mcp-server
Description: Model Context Protocol (MCP) server for Kubernetes — TypeScript/npm implementation
Author: tomeriva
Latest version: 0.3.0

# @iwaneo/kubernetes-mcp-server

[![npm](https://img.shields.io/npm/v/@iwaneo/kubernetes-mcp-server)](https://www.npmjs.com/package/@iwaneo/kubernetes-mcp-server)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

Model Context Protocol (MCP) server for Kubernetes — TypeScript/npm implementation.

Inspired by [containers/kubernetes-mcp-server](https://github.com/containers/kubernetes-mcp-server), built natively in TypeScript using the official `@kubernetes/client-node` SDK.

---

## Features

- **Configuration**: View kubeconfig, list contexts and targets
- **Pods**: List, get, delete, logs, exec, top, run
- **Namespaces**: List all namespaces
- **Events**: List events (cluster-wide or per-namespace)
- **Nodes**: Top (metrics), logs, stats summary
- **Generic Resources**: CRUD on any Kubernetes resource (Deployment, Service, Ingress, CRDs, ...)
- **Helm**: List, install, uninstall releases (requires `helm` CLI)
- **Read-only mode**: `--read-only` disables all write/delete operations
- **Toolset filtering**: Enable only the toolsets you need

---

## Getting Started

### Claude Desktop

```json
{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "@iwaneo/kubernetes-mcp-server@latest"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add --transport stdio kubernetes \
  -- npx -y @iwaneo/kubernetes-mcp-server@latest
```

### With all toolsets (including Helm)

```json
{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": [
        "-y",
        "@iwaneo/kubernetes-mcp-server@latest",
        "--toolsets", "config,core,helm"
      ]
    }
  }
}
```

### Read-only mode

```json
{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": [
        "-y",
        "@iwaneo/kubernetes-mcp-server@latest",
        "--read-only"
      ]
    }
  }
}
```

---

## Configuration

| Option | Description | Default |
|--------|-------------|---------|
| `--read-only` | Disable all write/delete operations | `false` |
| `--disable-destructive` | Disable delete/update operations | `false` |
| `--toolsets <list>` | Comma-separated toolsets to enable | `config,core` |
| `--kubeconfig <path>` | Path to kubeconfig file | auto-detect |
| `--log-level <0-9>` | Logging verbosity | `0` |

---

## Available Toolsets

| Toolset | Default | Description |
|---------|---------|-------------|
| `config` | ✓ | View kubeconfig, list contexts and targets |
| `core` | ✓ | Pods, namespaces, events, nodes, generic resources |
| `helm` | | Helm release management (requires `helm` CLI) |

---

## Tools Reference

### config toolset

| Tool | Description |
|------|-------------|
| `configuration_view` | Get current kubeconfig as YAML |
| `configuration_contexts_list` | List all contexts with server URLs |
| `targets_list` | List all available targets |

### core toolset

| Tool | Description |
|------|-------------|
| `pods_list` | List pods across all namespaces |
| `pods_list_in_namespace` | List pods in a specific namespace |
| `pods_get` | Get a pod by name |
| `pods_delete` | Delete a pod (write mode only) |
| `pods_log` | Get pod logs |
| `pods_exec` | Execute a command in a pod |
| `pods_top` | Pod CPU/memory usage |
| `pods_run` | Run a container image as a pod (write mode only) |
| `namespaces_list` | List all namespaces |
| `events_list` | List events (optionally filtered by namespace) |
| `nodes_top` | Node CPU/memory usage |
| `nodes_log` | Get node logs via kubelet API |
| `nodes_stats_summary` | Detailed node stats from kubelet |
| `resources_list` | List any Kubernetes resource by apiVersion + kind |
| `resources_get` | Get a resource by apiVersion + kind + name |
| `resources_create_or_update` | Create or update a resource from YAML/JSON (write mode only) |
| `resources_delete` | Delete a resource (write mode only) |
| `resources_scale` | Get/set replica count for Deployment/StatefulSet (write mode only) |

### helm toolset

| Tool | Description |
|------|-------------|
| `helm_list` | List Helm releases |
| `helm_install` | Install a Helm chart (write mode only) |
| `helm_uninstall` | Uninstall a Helm release (write mode only) |

---

## Requirements

- Node.js >= 18
- Access to a Kubernetes cluster (via kubeconfig or in-cluster)
- For `nodes_top` / `pods_top`: Metrics Server installed in the cluster
- For `helm` toolset: `helm` CLI installed and in PATH

---

## Development

```bash
git clone https://github.com/tomeriva/kubernetes-mcp-server
cd kubernetes-mcp-server
npm install
npm run build
node dist/index.js --help
```

### Local install in Claude Code

```bash
npm run build
claude mcp add --transport stdio kubernetes \
  -- node $(pwd)/dist/index.js --toolsets config,core,helm
```

---

## Publishing

```bash
npm login
npm publish --access public
```

---

## License

Apache-2.0