Getting Started - cturner8/kube-mcp GitHub Wiki

This guide will help you get kube-mcp up and running and connected to your MCP client.

What is kube-mcp?

kube-mcp is an in-cluster MCP (Model Context Protocol) server that allows AI assistants to interact with your Kubernetes cluster. It provides a secure, read-only interface to query cluster resources like pods, deployments, services, and more.

Key Features

  • In-cluster deployment: Runs inside your Kubernetes cluster with no need to expose the Kubernetes API externally
  • OIDC authentication: Secure access via your existing identity provider (Azure AD, Okta, Auth0, etc.)
  • Kubernetes RBAC: Leverages native Kubernetes permissions for fine-grained access control
  • Configurable tools: Control which actions/operations AI assistants can access

Prerequisites

Before you begin, ensure you have:

  • A Kubernetes cluster (v1.19+)
  • Helm 3.8+
  • An OIDC provider with a registered client application
  • An MCP-compatible client (see Supported Clients)

Deployment

Follow the Helm Install guide to deploy kube-mcp to your cluster. At minimum, you'll need to configure:

  1. Base URL: The externally accessible URL for kube-mcp
  2. OIDC settings: Issuer URL and Client ID from your identity provider
  3. Ingress: To expose the service (or use port-forwarding for testing)

Configuring Your MCP Client

kube-mcp uses the HTTP streamable transport and requires OAuth authentication. Configuration varies by client.

Supported Clients

Any MCP client that supports:

  • HTTP transport
  • OAuth 2.0 authentication with OIDC (technically optional but provides a better user experience)

VS Code with GitHub Copilot

Add the following to your VS Code mcp.json:

{
  "servers": {
    "kube-mcp": {
      "type": "http",
      "url": "https://mcp.example.com"
    }
  }
}

When you first interact with the server, you'll be prompted to authenticate via your OIDC provider.

Claude Desktop

Add to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "kube-mcp": {
      "type": "http",
      "url": "https://mcp.example.com"
    }
  }
}

Other Clients

For other MCP clients, configure:

  • Server URL: Your kube-mcp base URL (e.g., https://mcp.example.com)
  • Transport: HTTP
  • Authentication: OAuth 2.0 / Bearer token

The server exposes Protected Resource Metadata at /.well-known/oauth-protected-resource which compatible clients use to discover authentication requirements automatically.

If your MCP client does not support PRM discovery, you can instead provide an Authorization token manually via request headers. Example VS Code mcp.json configuration:

{
  "inputs": [
    {
      "id": "access-token",
      "description": "Enter your authentication access token",
      "type": "promptString"
    }
  ],
  "servers": {
    "kube-mcp": {
      "type": "http",
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer ${input:access-token}"
      }
    }
  }
}

Verifying the Connection

Once configured, you can verify the connection by asking your AI assistant to:

"List the namespaces in my Kubernetes cluster"

or

"What pods are running in the default namespace?"

If authentication is successful, you should see results from your cluster.

Next Steps