# K8s Cluster Ops MCP Server (`bronze_quarterback/k8s-cluster-ops-mcp`) Actor

Operate your Kubernetes cluster via natural language. Get pod logs, scale deployments, check cluster health, apply manifests, and restart services. All mutating operations require explicit confirmation.

- **URL**: https://apify.com/bronze\_quarterback/k8s-cluster-ops-mcp.md
- **Developed by:** [Segun Zubair](https://apify.com/bronze_quarterback) (community)
- **Categories:** AI, Developer tools
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

$49.00/month + usage

To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month.You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#rental-actors

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## K8s Cluster Ops MCP Server

Manage Kubernetes clusters through natural language — list resources, inspect logs, scale deployments, apply manifests, and monitor cluster health. All mutating operations require explicit confirmation.

### Quick Start

1. **Deploy on Apify** — search "K8s Cluster Ops MCP" in the [Apify Store](https://apify.com/store), or run locally with Docker.
2. **Add the MCP server URL** to your Claude Desktop config (`claude_desktop_config.json`):
   ```json
   {
     "mcpServers": {
       "k8s-cluster-ops": {
         "url": "https://your-apify-actor-standby-url/sse"
       }
     }
   }
````

3. **Start managing your cluster** with natural language in Claude.

#### Run locally

```bash
git clone <repo-url>
cd products/mcp-servers/k8s-cluster-ops

## Ensure kubectl is installed and kubeconfig is set
export KUBECONFIG="$HOME/.kube/config"

pip install -r requirements.txt
python src/server.py
```

The server starts on port 8080 by default (configure with `PORT` env var).

### Configuration

| Parameter | Required | Description | Default |
|-----------|----------|-------------|---------|
| `KUBECONFIG` | No | Path to kubeconfig file | `~/.kube/config` |
| `KUBECTL_PATH` | No | Path to kubectl binary | `kubectl` |
| `HOST` | No | Server bind address | `0.0.0.0` |
| `PORT` | No | Server port | `8080` |

### Available Tools

#### list\_namespaces

List all namespaces in the cluster with their status and labels.

**Parameters:** None.

**Example prompt:** *"What namespaces exist in my cluster?"*

**Example response:**

```json
{
  "count": 4,
  "namespaces": [
    { "name": "default", "status": "Active", "labels": {} },
    { "name": "production", "status": "Active", "labels": { "env": "prod" } },
    { "name": "staging", "status": "Active", "labels": { "env": "staging" } },
    { "name": "kube-system", "status": "Active", "labels": {} }
  ]
}
```

#### list\_pods

List all pods in a namespace with status, readiness, and restart counts.

**Parameters:** `namespace` (required).

**Example prompt:** *"Show me all pods in the production namespace"*

#### list\_deployments

List deployments in a namespace with replica counts and images.

**Parameters:** `namespace` (required).

**Example prompt:** *"What deployments are running in staging?"*

#### list\_services

List services in a namespace with type, ClusterIP, and port mappings.

**Parameters:** `namespace` (required).

**Example prompt:** *"List all services in the production namespace"*

#### get\_pod\_logs

Tail logs from a specific pod.

**Parameters:** `namespace` (required), `pod_name` (required), `container` (optional), `tail_lines` (optional, default 100, max 1000).

**Example prompt:** *"Show me the last 50 lines of logs from the api-server pod in production"*

#### describe\_resource

Get a detailed description of any Kubernetes resource (equivalent to `kubectl describe`).

**Parameters:** `namespace` (required), `resource_type` (required), `resource_name` (required).

**Example prompt:** *"Describe the redis deployment in the cache namespace"*

#### scale\_deployment

Scale a deployment's replica count. **Requires `confirm: true`.**

**Parameters:** `namespace` (required), `deployment_name` (required), `replicas` (required), `confirm` (required, must be `true`).

**Example prompt:** *"Scale the web-frontend deployment in production to 5 replicas"*

Without `confirm: true`, returns a preview:

```json
{
  "warning": true,
  "message": "This will scale deployment 'web-frontend' in namespace 'production' to 5 replicas. To proceed, call this tool again with confirm=true.",
  "confirm_required": true
}
```

#### apply\_manifest

Apply a YAML manifest to the cluster. Supports dry-run mode. **Requires `confirm: true` for actual apply.**

**Parameters:** `manifest_yaml` (required), `namespace` (optional), `dry_run` (optional, default false), `confirm` (required for non-dry-run).

**Example prompt:** *"Apply this ConfigMap to the staging namespace (dry run first)"*

#### get\_cluster\_health

Aggregate cluster health status — nodes, PVCs, and namespace overview.

**Parameters:** None.

**Example prompt:** *"How healthy is my cluster right now?"*

#### restart\_deployment

Perform a rolling restart of a deployment. **Requires `confirm: true`.**

**Parameters:** `namespace` (required), `deployment_name` (required), `confirm` (required, must be `true`).

**Example prompt:** *"Rolling restart the api-server deployment in production"*

### Safety Guardrails

- **Mutating operations** (`scale_deployment`, `apply_manifest`, `restart_deployment`) require `confirm: true`. Without it, the tool returns a warning describing what would happen.
- **Blocked operations**: `kubectl delete namespace` and `kubectl delete node` are permanently blocked.
- **Dry-run support**: `apply_manifest` supports `dry_run: true` to preview changes without applying.
- **Namespace required**: All pod/deployment/service operations require an explicit namespace — the server never defaults to `default`.

### Example Prompts

- "What namespaces exist in my cluster?"
- "Show me all pods in the production namespace"
- "Are there any pods crashing in staging?"
- "Show me the logs for the auth-service pod in production"
- "Scale the web-frontend to 3 replicas in staging"
- "How healthy is my cluster?"
- "Apply this deployment manifest to production (dry run first)"
- "Rolling restart the api-gateway in production"

### Pricing

| Plan | Price | Includes |
|------|-------|----------|
| **Starter** | $49/mo | Read-only tools (list, logs, describe, health) |
| **Pro** | $149/mo | All tools including scale, apply, and restart |

Purchase on [Apify Store](https://apify.com/store) or [MCPize](https://mcpize.com).

### Local Development

```bash
## Install dependencies
pip install -r requirements.txt

## Run with hot reload (development)
python src/server.py

## Run tests
pytest tests/ -v

## Build Docker image
docker build -t k8s-cluster-ops-mcp .
docker run -p 8080:8080 \
  -v "$HOME/.kube/config:/root/.kube/config:ro" \
  k8s-cluster-ops-mcp
```

### Troubleshooting

| Issue | Solution |
|-------|----------|
| `kubectl not found` | Install kubectl or set `KUBECTL_PATH` to its location |
| `connection refused` | Ensure your kubeconfig points to a reachable cluster |
| `forbidden` | Check RBAC — your kubeconfig user needs appropriate permissions |
| `confirm required` | Mutating operations need `confirm: true` — this is by design |
| Timeout errors | The cluster may be unreachable; check network connectivity |

# Actor input Schema

## `kubeconfigPath` (type: `string`):

Path to your kubeconfig file. Defaults to ~/.kube/config.

## `kubeconfigBase64` (type: `string`):

Alternative: paste your kubeconfig as a base64-encoded string. Takes priority over kubeconfigPath if provided.

## `kubectlPath` (type: `string`):

Path to the kubectl binary. Defaults to 'kubectl' (assumes it's in PATH).

## Actor input object example

```json
{
  "kubeconfigPath": "~/.kube/config",
  "kubectlPath": "kubectl"
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("bronze_quarterback/k8s-cluster-ops-mcp").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("bronze_quarterback/k8s-cluster-ops-mcp").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call bronze_quarterback/k8s-cluster-ops-mcp --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=bronze_quarterback/k8s-cluster-ops-mcp",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "K8s Cluster Ops MCP Server",
        "description": "Operate your Kubernetes cluster via natural language. Get pod logs, scale deployments, check cluster health, apply manifests, and restart services. All mutating operations require explicit confirmation.",
        "version": "1.0",
        "x-build-id": "ICdRW9nJpVI6Ijmku"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/bronze_quarterback~k8s-cluster-ops-mcp/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-bronze_quarterback-k8s-cluster-ops-mcp",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/bronze_quarterback~k8s-cluster-ops-mcp/runs": {
            "post": {
                "operationId": "runs-sync-bronze_quarterback-k8s-cluster-ops-mcp",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/bronze_quarterback~k8s-cluster-ops-mcp/run-sync": {
            "post": {
                "operationId": "run-sync-bronze_quarterback-k8s-cluster-ops-mcp",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "kubeconfigPath": {
                        "title": "Kubeconfig Path",
                        "type": "string",
                        "description": "Path to your kubeconfig file. Defaults to ~/.kube/config.",
                        "default": "~/.kube/config"
                    },
                    "kubeconfigBase64": {
                        "title": "Kubeconfig (Base64)",
                        "type": "string",
                        "description": "Alternative: paste your kubeconfig as a base64-encoded string. Takes priority over kubeconfigPath if provided."
                    },
                    "kubectlPath": {
                        "title": "kubectl Path",
                        "type": "string",
                        "description": "Path to the kubectl binary. Defaults to 'kubectl' (assumes it's in PATH).",
                        "default": "kubectl"
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```