Kubernetes Runbooks 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

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