thoraxe/kube-health-mcp

Kube-Health MCP Server

This project implements an MCP (Model Context Protocol) server that exposes the kube-health tool for investigating Kubernetes object health.

Overview

The MCP server provides a single tool called kube_health that allows you to investigate the health status of Kubernetes objects by specifying the object name (e.g., deployment/my-app, pod/my-pod, service/my-service).

Prerequisites

• Python 3.8 or higher
• The kube-health binary in the bin/ directory (included)
• Access to a Kubernetes cluster (configured via kubeconfig)

Installation

1. Install the required dependencies:

   pip install -r requirements.txt
   

2. Make sure the kube-health binary is executable:

   chmod +x bin/kube-health
   

Usage

Running the MCP Server

The server can be run in different modes depending on your needs:

STDIO Mode (Default)

For local tools and Claude Desktop integration:

python server.py

HTTP Mode

For web deployments and remote access:

# Using environment variables
MCP_TRANSPORT=http MCP_PORT=9000 python server.py

# Or using a .env file
echo "MCP_TRANSPORT=http" > .env
echo "MCP_PORT=9000" >> .env
python server.py

Custom Configuration

Set environment variables for custom configuration:

export MCP_TRANSPORT=http
export MCP_HOST=0.0.0.0
export MCP_PORT=8080
export MCP_PATH=/kube-health/
export MCP_LOG_LEVEL=debug
python server.py

The server will start and listen for MCP client connections using the FastMCP library.

Using the Tool

The server exposes one tool:

kube_health

Description: Investigate the health of a Kubernetes object using the kube-health tool.

Parameters:

• object_name (string): The Kubernetes object to investigate

Examples:

• deployment/my-app - Check health of a deployment named "my-app"
• pod/my-pod - Check health of a pod named "my-pod"
• service/my-service - Check health of a service named "my-service"
• namespace/my-namespace - Check health of a namespace named "my-namespace"

Transport

This server supports the Streamable HTTP transport as specified in the MCP specification. The FastMCP library handles the transport layer automatically.

Configuration

Environment Variables

The server can be configured using environment variables. Copy example.env to .env and modify as needed:

cp example.env .env

Available Environment Variables:

Transport Types:

• stdio (default): Standard input/output communication (recommended for local tools and Claude Desktop)
• http: Streamable HTTP transport (recommended for web deployments and remote access)
• sse: Server-Sent Events transport (deprecated, use http instead)

Kubernetes Configuration

The server will use your existing Kubernetes configuration (kubeconfig) to connect to your cluster. Make sure you have:

1. A valid kubeconfig file (usually at ~/.kube/config)
2. Proper permissions to access the Kubernetes resources you want to monitor

You can also set Kubernetes-specific environment variables:

• KUBECONFIG: Path to your kubeconfig file
• Standard Kubernetes environment variables for in-cluster access

Troubleshooting

• "kube-health binary not found": Ensure the bin/kube-health file exists and is in the correct location
• "binary is not executable": Run chmod +x bin/kube-health to make it executable
• Connection errors: Verify your kubeconfig is properly configured and you have access to the cluster
• Timeout errors: The tool has a 30-second timeout; complex queries on large clusters may need adjustment

Development

The server is built using the FastMCP library, which provides a simple way to create MCP servers in Python. The main implementation is in server.py.

To modify or extend the server:

1. Edit server.py to add new tools or modify existing ones
2. Use the @mcp.tool() decorator to register new tools
3. Follow the MCP specification for tool definitions and responses