Kubernetes Runbooks MCP Server

A Model Context Protocol (MCP) server that provides access to Kubernetes troubleshooting runbooks from Container Solutions' Runbooks.

Features

• 🔍 Search & Discovery: Find relevant runbooks by keyword or browse all available topics

• 📖 Content Access: Fetch detailed troubleshooting guides for specific Kubernetes issues

• 🤖 AI Integration: Designed for seamless integration with AI assistants via MCP

• ⚡ Performance: Intelligent caching to minimize network requests

• 🛡️ Reliability: Robust error handling and graceful degradation

Related MCP server: Kubernetes MCP Server

Available Runbooks

The server provides access to comprehensive troubleshooting guides for:

• Node Issues: Resource constraints, node availability problems

• Pod Problems: CrashLoopBackOff, ImagePullBackOff, pending states

• Container Errors: CreateContainerError, sandbox creation failures

• Network Issues: Service connectivity, DNS resolution problems

• Resource Management: OutOfPods states, resource allocation issues

Installation

Using uvx (Recommended)

Install and run directly with uvx:

uvx kubernetes-runbooks-mcp-server

Using uv

uv tool install kubernetes-runbooks-mcp-server
kubernetes-runbooks-server

Using pip

pip install kubernetes-runbooks-mcp-server
kubernetes-runbooks-server

Usage

With Claude Desktop

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

{
  "mcpServers": {
    "kubernetes-runbooks": {
      "command": "uvx",
      "args": ["kubernetes-runbooks-mcp-server"]
    }
  }
}

Available Tools

• list-topics: List all available runbook topics

• search-runbooks: Search runbooks by keyword

• fetch-runbook: Get specific runbook content by topic slug

Available Resources

Access runbooks directly via URI:

• runbook://kubernetes/create-container-error

• runbook://kubernetes/crashloopbackoff

• runbook://kubernetes/dns-failures

Available Prompts

• troubleshoot-k8s: Interactive troubleshooting guidance

• runbook-summary: Summarize key points from runbooks

Example Usage

# List all available topics
{"name": "list-topics", "arguments": {}}

# Search for pod-related issues
{"name": "search-runbooks", "arguments": {"query": "pod"}}

# Fetch specific runbook
{"name": "fetch-runbook", "arguments": {"topic": "crashloopbackoff"}}

Development

Setup

git clone <repository-url>
cd kubernetes-runbooks-mcp-server
uv sync --dev

Running

uv run kubernetes-runbooks-server

Testing

uv run pytest

Architecture

• RunbookScraper: Handles web scraping from the runbooks website

• Caching System: In-memory cache for runbook metadata and content

• MCP Server: Implements the Model Context Protocol with resources, tools, and prompts

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

• Container Solutions for maintaining excellent Kubernetes runbooks

• Model Context Protocol for the MCP specification