playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

Kubernetes MCP server

Integrates with Kubernetes clusters to provide resource management, monitoring, and troubleshooting capabilities across multiple contexts with pod log retrieval, event filtering, and multi-cluster operations.
Back to servers
Setup instructions
Provider
kkb0318
Release date
Jun 29, 2025
Language
Java
Stats
27 stars
View on GitHub

The Kubernetes MCP Server provides safe, read-only access to Kubernetes resources for debugging and inspection. It allows comprehensive cluster visibility without modification capabilities, making it ideal for secure monitoring and troubleshooting of Kubernetes environments.

Installation

Prerequisites

  • Kubernetes cluster access with a valid kubeconfig file
  • Go 1.24+ (for building from source)

Installation Methods

Using Go (Recommended)

go install github.com/kkb0318/kubernetes-mcp@latest

The binary will be available at $GOPATH/bin/kubernetes-mcp (or $HOME/go/bin/kubernetes-mcp if GOPATH is not set).

Building from Source

git clone https://github.com/kkb0318/kubernetes-mcp.git
cd kubernetes-mcp
go build -o kubernetes-mcp .

Configuration

Setting Up as an MCP Server

Add the server to your MCP configuration:

Basic Configuration

This setup automatically uses ~/.kube/config:

{
  "mcpServers": {
    "kubernetes": {
      "command": "/path/to/kubernetes-mcp"
    }
  }
}

With Custom Kubeconfig

{
  "mcpServers": {
    "kubernetes": {
      "command": "/path/to/kubernetes-mcp",
      "env": {
        "KUBECONFIG": "/path/to/your/kubeconfig"
      }
    }
  }
}

Standalone Usage

# Using default kubeconfig (~/.kube/config)
./kubernetes-mcp

# Using custom kubeconfig path
KUBECONFIG=/path/to/your/kubeconfig ./kubernetes-mcp

Available Tools

list_resources

Lists and filters Kubernetes resources with advanced options.

Parameters:

  • context (optional): Kubernetes context name from kubeconfig
  • kind (required): Resource type (Pod, Deployment, Service, etc.) or "all" for discovery
  • groupFilter (optional): Filter by API group substring
  • namespace (optional): Target namespace
  • labelSelector (optional): Filter by labels (e.g., "app=nginx")
  • fieldSelector (optional): Filter by fields
  • limit (optional): Maximum number of resources to return
  • timeoutSeconds (optional): Request timeout (default: 30s)
  • showDetails (optional): Return full resource objects

Examples:

// List pods with label selector
{
  "kind": "Pod",
  "namespace": "default",
  "labelSelector": "app=nginx"
}

// Discover FluxCD resources
{
  "kind": "all",
  "groupFilter": "flux"
}

describe_resource

Gets detailed information about a specific Kubernetes resource.

Parameters:

  • context (optional): Kubernetes context name
  • kind (required): Resource type
  • name (required): Resource name
  • namespace (optional): Target namespace

Example:

{
  "kind": "Pod",
  "name": "nginx-pod",
  "namespace": "default"
}

get_pod_logs

Retrieves pod logs with filtering options.

Parameters:

  • context (optional): Kubernetes context name
  • name (required): Pod name
  • namespace (optional): Pod namespace (defaults to "default")
  • container (optional): Specific container name
  • tail (optional): Number of lines from the end (default: 100)
  • since (optional): Duration like "5s", "2m", "3h"
  • sinceTime (optional): RFC3339 timestamp
  • timestamps (optional): Include timestamps in output
  • previous (optional): Get logs from previous container instance

Example:

{
  "name": "nginx-pod",
  "namespace": "default",
  "tail": 50,
  "since": "5m",
  "timestamps": true
}

list_events

Lists and filters Kubernetes events for debugging and monitoring.

Parameters:

  • context (optional): Kubernetes context name
  • namespace (optional): Target namespace
  • object (optional): Filter by object name
  • eventType (optional): Filter by event type: "Normal" or "Warning"
  • reason (optional): Filter by event reason
  • since (optional): Duration like "5s", "2m", "1h"
  • sinceTime (optional): RFC3339 timestamp
  • limit (optional): Maximum number of events to return (default: 100)
  • timeoutSeconds (optional): Request timeout (default: 30s)

Examples:

// List recent warning events
{
  "eventType": "Warning",
  "since": "30m"
}

// List events for a specific pod
{
  "object": "nginx-pod",
  "namespace": "default"
}

list_contexts

Lists all available Kubernetes contexts from your kubeconfig file.

Parameters: None

Example Response:

{
  "contexts": [
    {
      "name": "production-cluster",
      "is_current": false
    },
    {
      "name": "staging-cluster", 
      "is_current": true
    },
    {
      "name": "development-cluster",
      "is_current": false
    }
  ],
  "current_context": "staging-cluster",
  "total": 3
}

Advanced Features

Multi-Cluster Support

All tools support an optional context parameter to specify which cluster to query:

// Query production cluster
{
  "kind": "Pod",
  "context": "production-cluster",
  "namespace": "default"
}

Custom Resource Definition (CRD) Support

The server automatically discovers and works with any CRDs in your cluster. Simply use the CRD's Kind name with list_resources or describe_resource tools.

Smart Resource Discovery

Use the groupFilter parameter to discover resources by API group substring:

  • "flux" - Discovers FluxCD resources
  • "argo" - Discovers ArgoCD resources
  • "istio" - Discovers Istio resources
  • "cert-manager" - Discovers cert-manager resources

Security Features

  • Read-only access - No resource creation, modification, or deletion
  • Production safe - Secure for use in production environments
  • Minimal permissions - Only requires read access to cluster resources

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "kubernetes" '{"command":"/path/to/kubernetes-mcp"}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "kubernetes": {
            "command": "/path/to/kubernetes-mcp"
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "kubernetes": {
            "command": "/path/to/kubernetes-mcp"
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later