Kubernetes read-only MCP server

Kubernetes read-only MCP server

mcp-kubernetes-ro is a Model Context Protocol (MCP) server providing read-only access to Kubernetes clusters for AI assistants. It enables AI models to list resources, get resource details, retrieve pod logs, discover API resources, and perform base64 encoding/decoding operations - all while maintaining security through read-only access.

The server leverages your local kubectl configuration (even when kubectl is not required to be installed) and provides a safe, read-only interface to your Kubernetes clusters, preventing any destructive operations while allowing comprehensive cluster inspection and troubleshooting capabilities.

Features

• Does not require kubectl: The MCP server uses your local kubectl configuration to connect to your Kubernetes cluster but not the binary, so it works even when kubectl is not installed on your machine.
• Resource Listing: List any Kubernetes resources by type with optional filtering by labels, fields, and namespaces
• Resource Details: Get complete details for specific Kubernetes resources
• Pod Logs: Retrieve pod logs with advanced filtering options including grep patterns, time filtering, and previous logs
• Container Discovery: List containers within pods for targeted log access
• API Discovery: Discover available Kubernetes API resources and their capabilities
• Base64 Utilities: Encode and decode base64 data for Kubernetes secrets and configurations
• Multiple Transport Modes: Support for both stdio and Server-Sent Events (SSE) communication
• Read-Only Security: Complete prevention of destructive operations while maintaining full inspection capabilities
• Namespace Support: Work with specific namespaces or cluster-wide resources
• Advanced Filtering: Support for label selectors, field selectors, and pagination
• Per-Command Context: Specify different Kubernetes contexts for individual commands
• Environment Variable Support: Automatic detection of KUBECONFIG environment variable
• Startup Connectivity Check: Automatic validation of cluster connectivity and basic permissions on startup

Installation

Feel free to grab a pre-built binary from the releases page.

Alternatively, you can use Homebrew in macOS or Linux to install it:

brew install patrickdappollonio/tap/mcp-kubernetes-ro

Finally, Docker users can use the prebuilt image from the GitHub Container Registry:

docker pull ghcr.io/patrickdappollonio/mcp-kubernetes-ro:latest

Editor Configuration

Add the following configuration to your editor's settings to use mcp-kubernetes-ro:

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "mcp-kubernetes-ro",
      "args": [
        // Uncomment and modify as needed:
        // "--kubeconfig=/path/to/kubeconfig",
        // "--namespace=default",
        // "--transport=stdio",
        // "--port=8080"
      ],
      "env": {
        // Set KUBECONFIG environment variable if needed:
        // "KUBECONFIG": "/path/to/kubeconfig"
      }
    }
  }
}

You can use mcp-kubernetes-ro directly from your $PATH as shown above, or provide the full path to the binary (e.g., /path/to/mcp-kubernetes-ro).

And this is how to leverage the Docker image instead:

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "KUBECONFIG=/root/.kube/config",
        "-v", "/path/to/kubeconfig:/root/.kube/config",
        "ghcr.io/patrickdappollonio/mcp-kubernetes-ro"
      ]
    },
  }
}

Do note that you'll need to mount your kubeconfig file into the container, and either set the KUBECONFIG environment variable to the path of the mounted file, or use the --kubeconfig flag to set it.

Prerequisites

• A valid Kubernetes configuration file (typically ~/.kube/config)
• Valid credentials and cluster access (kubectl binary is not required)
• Appropriate RBAC permissions for read operations
• Metrics Server (required for metrics tools): For metrics functionality (get_node_metrics, get_pod_metrics), the metrics-server must be installed in your cluster. If not available, these tools will return an error message.

Available MCP Tools

There are 10 tools available:

• list_resources: List any Kubernetes resources by type with optional filtering, sorted newest first
• get_resource: Get specific resource details
• get_logs: Get pod logs with advanced filtering options including grep patterns, time filtering, and previous logs
• get_pod_containers: List containers in a pod for log access
• list_api_resources: List available Kubernetes API resources with their details (similar to kubectl api-resources)
• list_contexts: List available Kubernetes contexts from the kubeconfig file
• get_node_metrics: Get node metrics (CPU and memory usage)
• get_pod_metrics: Get pod metrics (CPU and memory usage)
• encode_base64: Encode text data to base64 format
• decode_base64: Decode base64 data to text format

Running Modes

Standard (stdio) Mode

By default, mcp-kubernetes-ro runs in stdio mode, which is suitable for integration with editors and other tools that communicate via standard input/output.

mcp-kubernetes-ro

Server-Sent Events (SSE) Mode

Alternatively, you can run mcp-kubernetes-ro as an HTTP server with SSE support for web-based integrations:

mcp-kubernetes-ro --transport=sse --port=8080

In SSE mode, the server will listen on the specified port (default: 8080) and provide the same MCP tools over HTTP using Server-Sent Events. This is useful for web applications or environments where stdio communication isn't practical.

Configuration Options

The following command-line flags are available to configure the MCP server:

Kubernetes Configuration

• --kubeconfig=PATH: Path to kubeconfig file (defaults to KUBECONFIG environment variable, then ~/.kube/config)
• --namespace=NAME: Default namespace for operations (defaults to current namespace)

Transport Options

• --transport=TYPE: Transport type: stdio or sse (default: stdio)
• --port=PORT: Port for SSE server (default: 8080, only used with --transport=sse)

Context Configuration

The server supports per-command context. This provides more flexibility when working with multiple Kubernetes clusters or contexts within the same $KUBECONFIG file.

Configuration Priority:

1. Command-level context: Use the context parameter in individual tool calls
2. Kubeconfig default: Use the current context specified in your kubeconfig file

Kubeconfig Resolution Priority:

1. Command-line flag: --kubeconfig parameter
2. Environment variable: KUBECONFIG environment variable
3. Default path: ~/.kube/config
4. In-cluster config: Automatic detection when running inside a Kubernetes pod

Examples:

{
  "resource_type": "pods",
  "namespace": "default",
  "context": "production-cluster"
}

This approach allows you to:

• Use different contexts for different operations in the same session
• Switch contexts per command without restarting the server
• Maintain compatibility with existing kubeconfig setups

Tool Usage Documentation

List Resources

Lists any Kubernetes resources by type with optional filtering, sorted newest first.

Arguments:

• resource_type (required): The type of resource to list - use plural form (e.g., 'pods', 'deployments', 'services')
• api_version (optional): API version for the resource (e.g., 'v1', 'apps/v1')
• namespace (optional): Target namespace (leave empty for cluster-scoped resources)
• context (optional): Kubernetes context to use (defaults to current context from kubeconfig)
• label_selector (optional): Label selector to filter resources (e.g., 'app=nginx,version=1.0')
• field_selector (optional): Field selector to filter resources (e.g., 'status.phase=Running')
• limit (optional): Maximum number of resources to return (defaults to all)
• continue (optional): Continue token for pagination (from previous response)

Example:

{
  "resource_type": "pods",
  "namespace": "default",
  "context": "production",
  "label_selector": "app=nginx"
}

Get Resource

Gets specific resource details with complete configuration.

Arguments:

• resource_type (required): The type of resource to get
• name (required): Resource name
• api_version (optional): API version for the resource (e.g., 'v1', 'apps/v1')
• namespace (optional): Target namespace (required for namespaced resources)
• context (optional): Kubernetes context to use (defaults to current context from kubeconfig)

Example:

{
  "resource_type": "deployment",
  "name": "nginx-deployment",
  "namespace": "default",
  "context": "production"
}

Get Logs

Gets pod logs with advanced filtering options including grep patterns, time filtering, and previous logs.

Arguments:

• namespace (required): Pod namespace
• name (required): Pod name
• container (optional): Container name (required for multi-container pods)
• context (optional): Kubernetes context to use (defaults to current context from kubeconfig)
• max_lines (optional): Maximum number of lines to retrieve
• grep_include (optional): Include only lines matching these patterns (comma-separated). Works like grep - includes lines containing any of these patterns
• grep_exclude (optional): Exclude lines matching these patterns (comma-separated). Works like grep -v - excludes lines containing any of these patterns
• use_regex (optional): Whether to treat grep patterns as regular expressions instead of literal strings
• since (optional): Return logs newer than this time. Supports durations like "5m", "1h", "2h30m", "1d" or absolute times like "2023-01-01T10:00:00Z"
• previous (optional): Return logs from the previous terminated container instance (like kubectl logs --previous)

Example:

{
  "namespace": "default",
  "name": "nginx-pod-12345",
  "container": "nginx",
  "context": "production",
  "max_lines": "100",
  "grep_include": "error,warning",
  "since": "5m"
}

Get Pod Containers

Lists containers in a pod for log access.

Arguments:

• namespace (required): Pod namespace
• name (required): Pod name
• context (optional): Kubernetes context to use (defaults to current context from kubeconfig)

Example:

{
  "namespace": "default",
  "name": "nginx-pod-12345",
  "context": "production"
}

List API Resources

Lists available Kubernetes API resources with their details (similar to kubectl api-resources).

Arguments:

• None required

Example:

{}

List Contexts

Lists available Kubernetes contexts from the kubeconfig file. This is useful for discovering what contexts are available for use with the context parameter in other tools.

Arguments:

• None required

Example:

{}

Example Response:

{
  "contexts": [
    {
      "name": "production",
      "cluster": "prod-cluster",
      "user": "prod-user",
      "namespace": "default",
      "current": true
    },
    {
      "name": "staging",
      "cluster": "staging-cluster",
      "user": "staging-user",
      "namespace": "staging",
      "current": false
    }
  ],
  "count": 2
}

Get Node Metrics

Gets node metrics (CPU and memory usage) from the metrics server. Results are sorted by timestamp (newest first) for consistent ordering and pagination, since the built-in metrics server endpoint does not support needle-based pagination.

Arguments:

• node_name (optional): Specific node name to get metrics for. If not provided, returns metrics for all nodes.
• context (optional): Kubernetes context to use (defaults to current context from kubeconfig)
• limit (optional): Maximum number of node metrics to return. If not provided, returns all available metrics.
• continue (optional): Continue token for pagination (from previous response).

Error Handling:

• If the metrics server is not available, returns an error message
• Detects common metrics server errors and provides specific guidance

Example:

{
  "node_name": "worker-node-1",
  "context": "production",
  "limit": 5
}

Example Response (Single Node):

{
  "kind": "NodeMetrics",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "metadata": {
    "name": "worker-node-1",
    "creationTimestamp": "2023-01-01T12:00:00Z"
  },
  "timestamp": "2023-01-01T12:00:00Z",
  "window": "10.062s",
  "usage": {
    "cpu": "137m",
    "memory": "1368128Ki"
  }
}

Example Response (List with Pagination):

{
  "kind": "NodeMetricsList",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "count": 5,
  "items": [
    {
      "kind": "NodeMetrics",
      "metadata": { "name": "node-1" },
      "timestamp": "2023-01-01T12:00:00Z",
      "usage": { "cpu": "137m", "memory": "1368128Ki" }
    }
  ],
  "continue": "eyJvZmZzZXQiOjUsInR5cGUiOiJub2RlIiwibmFtZXNwYWNlIjoiIn0="
}

Get Pod Metrics

Gets pod metrics (CPU and memory usage) from the metrics server. Results are sorted by timestamp (newest first) for consistent ordering and pagination, since the built-in metrics server endpoint does not support needle-based pagination.

Arguments:

• namespace (optional): Namespace to get pod metrics from. If not provided, returns metrics for all pods in all namespaces.
• pod_name (optional): Specific pod name to get metrics for. Requires namespace if specified.
• context (optional): Kubernetes context to use (defaults to current context from kubeconfig)
• limit (optional): Maximum number of pod metrics to return. If not provided, returns all available metrics.
• continue (optional): Continue token for pagination (from previous response).

Error Handling:

• If the metrics server is not available, returns an error message
• Detects common metrics server errors and provides specific guidance
• Validates that namespace is provided when pod_name is specified

Pagination Notes:

• Continue tokens are context-aware and reset if the namespace context changes
• Client-side pagination is implemented for consistent ordering and filtering

Example (Specific Pod):

{
  "namespace": "kube-system",
  "pod_name": "metrics-server-557ff575fb-9dcl4",
  "context": "production"
}

Example (With Pagination):

{
  "namespace": "kube-system",
  "context": "production",
  "limit": 10,
  "continue": "eyJvZmZzZXQiOjEwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ=="
}

Example Response (Single Pod):

{
  "kind": "PodMetrics",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "metadata": {
    "name": "metrics-server-557ff575fb-9dcl4",
    "namespace": "kube-system",
    "creationTimestamp": "2023-01-01T12:00:00Z"
  },
  "timestamp": "2023-01-01T12:00:00Z",
  "window": "18.888s",
  "containers": [
    {
      "name": "metrics-server",
      "usage": {
        "cpu": "8020419n",
        "memory": "48164Ki"
      }
    }
  ]
}

Example Response (List with Pagination):

{
  "kind": "PodMetricsList",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "namespace": "kube-system",
  "count": 10,
  "items": [
    {
      "kind": "PodMetrics",
      "metadata": { "name": "pod-1", "namespace": "kube-system" },
      "timestamp": "2023-01-01T12:00:00Z",
      "containers": [
        {
          "name": "container-1",
          "usage": { "cpu": "8020419n", "memory": "48164Ki" }
        }
      ]
    }
  ],
  "continue": "eyJvZmZzZXQiOjIwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ=="
}

Encode Base64

Encodes text data to base64 format.

Arguments:

• data (required): Text data to encode

Example:

{
  "data": "username:password"
}

Decode Base64

Decodes base64 data to text format.

Arguments:

• data (required): Base64 data to decode

Example:

{
  "data": "dXNlcm5hbWU6cGFzc3dvcmQ="
}

Examples

Basic Usage Examples

# Start with default kubeconfig and context
mcp-kubernetes-ro

# Start with specific kubeconfig
mcp-kubernetes-ro --kubeconfig ~/.kube/config

# Start with KUBECONFIG environment variable
export KUBECONFIG=~/.kube/config
mcp-kubernetes-ro

# Start with specific namespace
mcp-kubernetes-ro --namespace kube-system

# Start in SSE mode
mcp-kubernetes-ro --transport=sse --port=3000

Advanced Configuration Examples

# Production cluster with specific kubeconfig
mcp-kubernetes-ro \
  --kubeconfig ~/.kube/prod-config \
  --namespace monitoring

# Development setup with SSE mode using environment variable
export KUBECONFIG=~/.kube/dev-config
mcp-kubernetes-ro \
  --transport=sse \
  --port=8080

# Using per-command context (specify context in tool calls)
# Context is now specified at the tool level, not globally

Use Cases

Cluster Troubleshooting

• List failing pods across namespaces
• Get detailed resource configurations
• Retrieve pod logs for debugging
• Discover available API resources

Resource Discovery

• Explore cluster resources by type
• Find resources with specific labels
• Understand resource relationships
• Identify resource configurations

Security and Compliance

• Read-only access prevents accidental changes
• Inspect configurations without modification risk
• Audit resource states and settings
• Safe exploration of production clusters

AI-Assisted Operations

• Let AI assistants help diagnose cluster issues
• Get intelligent suggestions for resource problems
• Automated log analysis and pattern recognition
• Natural language queries for Kubernetes resources

AI Assistant Considerations

While this MCP server provides comprehensive tools for Kubernetes cluster inspection, some AI assistants may have limitations or policies that prevent them from using certain tool combinations, even when technically available:

Potential Limitations

• Secret Access: Some AI assistants may refuse to retrieve, decode, or display Kubernetes secrets (even using the provided get_resource and decode_base64 tools) due to security policies around credential handling
• Sensitive Data: AI models may have built-in restrictions against exposing sensitive information in chat interfaces, regardless of user permissions or tool availability
• Security Patterns: Certain AI assistants prioritize security best practices over technical capability, potentially refusing operations that could expose sensitive data

Workarounds

If your AI assistant refuses to use available tools for security reasons:

1. Direct CLI Access: Use kubectl directly for sensitive operations, and just ask the AI to give you the command to run, for example:

   kubectl get secret <secret-name> -n <namespace> -o yaml
   echo "<base64-data>" | base64 -d
   

2. Manual Tool Usage: If using the MCP server programmatically, call the tools directly rather than through an AI assistant

3. Documentation: Consider the security implications - the AI's refusal might actually be protecting you from inadvertent credential exposure

Design Philosophy

This behavior reflects different approaches to security:

• Tool-based: If you have the tools and permissions, you should be able to use them
• AI-safety: Prioritize preventing accidental exposure over technical capability

Both perspectives are valid, and this limitation should be considered when designing workflows that involve sensitive data retrieval.

Startup Connectivity Check

The MCP server performs an automatic connectivity check on startup to verify that it can successfully connect to your Kubernetes cluster. This check includes:

1. API Server Reachability: Verifies that the Kubernetes API server is accessible and responding
2. Authentication: Confirms that your credentials are valid and accepted by the cluster
3. API Discovery: Tests that the server can discover available API resources
4. Basic Permissions: Validates that you have at least read access to namespaces (basic RBAC check)

What You'll See

On successful startup, you'll see output like:

Testing connectivity to Kubernetes cluster...
✓ Successfully connected to Kubernetes cluster (version: v1.28.0, 4 namespaces accessible)

Troubleshooting Connectivity Issues

If the connectivity check fails, you'll see a detailed error message. Common issues include:

• Invalid kubeconfig: Check that your kubeconfig file exists and is properly formatted
• Cluster unreachable: Verify that the cluster endpoint is accessible from your network
• Authentication failed: Ensure your credentials haven't expired and are valid
• Insufficient permissions: Verify you have at least read access to basic cluster resources

The connectivity check has a 30-second timeout to prevent hanging on unresponsive clusters.

Security Considerations

• Read-Only Access: The server only supports read operations (get, list, watch)
• Local Authentication: Uses your existing kubectl configuration and credentials
• No Destructive Operations: Cannot create, update, or delete resources
• Namespace Isolation: Respects RBAC permissions from your kubeconfig
• Secure Communication: Supports both stdio and HTTPS-based SSE communication

Metrics Implementation Details

Error Detection and Handling

The metrics tools (get_node_metrics and get_pod_metrics) include sophisticated error detection for metrics server availability:

• Automatic Detection: Detects when the metrics server is not installed or not responding
• Helpful Error Messages: Provides specific installation commands when metrics server is missing
• Common Error Patterns: Recognizes various metrics server error scenarios:
  • metrics-server service not found
  • metrics.k8s.io API group unavailable
  • "server could not find the requested resource" errors
  • "no metrics available" conditions

Pagination Implementation

Both metrics tools implement client-side pagination for consistent results, since the built-in metrics server endpoint does not support needle-based pagination, and also to provide a safe way for AI tools to request just the data they need, especially useful in small context windows.

• Sorting: All results are sorted by timestamp (newest first) before pagination
• Continue Tokens: Base64-encoded JSON tokens containing:
  • offset: Current position in the result set
  • type: Resource type ("node" or "pod")
  • namespace: Context namespace (for pod metrics)
• Context Awareness: Pagination state resets when namespace context changes
• Token Format: eyJvZmZzZXQiOjEwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ==

Resource Retrieval Strategy

• Fetch-Then-Filter: Always retrieves all available metrics from the server, then applies client-side filtering and pagination
• Consistent Ordering: Ensures predictable results across paginated requests
• Namespace Scoping: Automatically scopes pod metrics to specific namespaces when provided

Error Handling

The server provides detailed error messages for common issues:

• Invalid resource types or API versions
• Missing required parameters
• RBAC permission errors
• Network connectivity issues
• Malformed kubeconfig files
• Metrics server unavailability (with installation guidance)

Limitations

• Requires local kubectl configuration
• Read-only access only (no write operations)
• Limited to resources accessible by your kubeconfig credentials
• No real-time streaming of logs (static retrieval only)
• No support for custom resource definitions discovery beyond API resources