Provides access to Kubernetes troubleshooting runbooks for issues like node problems, pod problems, container errors, network issues, and resource management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@kubernetes-runbooks-mcp-server search runbooks for pod crashes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that provides access to Kubernetes troubleshooting runbooks from Container Solutions' Runbooks.
🔍 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: K8s Doctor MCP
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
Install and run directly with uvx:
uvx kubernetes-runbooks-mcp-serveruv tool install kubernetes-runbooks-mcp-server
kubernetes-runbooks-serverpip install kubernetes-runbooks-mcp-server
kubernetes-runbooks-serverAdd to your Claude Desktop configuration (claude_desktop_config.json):
{
"mcpServers": {
"kubernetes-runbooks": {
"command": "uvx",
"args": ["kubernetes-runbooks-mcp-server"]
}
}
}list-topics: List all available runbook topics
search-runbooks: Search runbooks by keyword
fetch-runbook: Get specific runbook content by topic slug
Access runbooks directly via URI:
runbook://kubernetes/create-container-error
runbook://kubernetes/crashloopbackoff
runbook://kubernetes/dns-failures
troubleshoot-k8s: Interactive troubleshooting guidance
runbook-summary: Summarize key points from runbooks
# 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"}}git clone <repository-url>
cd kubernetes-runbooks-mcp-server
uv sync --devuv run kubernetes-runbooks-serveruv run pytestRunbookScraper: 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
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
MIT License - see LICENSE file for details.
Container Solutions for maintaining excellent Kubernetes runbooks
Model Context Protocol for the MCP specification
Fetch a specific Kubernetes runbook by topic
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | The runbook topic/slug to fetch |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'Fetch' (implying a read operation) but does not disclose behavioral traits such as authentication requirements, error handling, or what happens if the topic does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no filler. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with one parameter and no output schema, the description is adequate but leaves gaps: it doesn't specify the return format, whether it returns raw content, or any error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the 'topic' parameter is described). The tool description adds no further detail beyond the schema's 'The runbook topic/slug to fetch', so it meets the baseline without adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch'), identifies the resource ('Kubernetes runbook'), and specifies the selection method ('by topic'). It clearly distinguishes from siblings: list-topics lists available topics, search-runbooks does full-text search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available Kubernetes runbook topics
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states 'List all available Kubernetes runbook topics'. This minimally discloses behavior as a simple read operation, but lacks details like whether the list is paginated or includes descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise, and front-loaded with the key verb 'List'. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description is minimally complete for a simple list. However, it doesn't specify the output format (e.g., topic names, IDs), which could be added for clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so baseline is 4. The description does not need to add parameter info since there are none, but it doesn't add any extra meaning either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all available Kubernetes runbook topics, using specific verb+resource. It distinguishes from siblings: fetch-runbook retrieves a specific runbook, search-runbooks searches, while this lists topics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need to see all topics, but provides no explicit guidance on when to use this vs. search-runbooks or fetch-runbook. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search through Kubernetes runbooks by keyword
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query for finding relevant runbooks |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only says 'search', implying read-only but lacks explicit disclosure of side effects, rate limits, or result behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, front-loaded with action verb and target. Very concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal description lacking details on output format, pagination, or limitations. For a search tool, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, parameter description 'Search query for finding relevant runbooks' adds minor context beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'search', resource 'Kubernetes runbooks', and method 'by keyword'. Distinguishes from sibling tools 'fetch-runbook' and 'list-topics' which imply retrieval of specific runbook or listing topics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. Implied usage for keyword-based search, but no exclusions or mention of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1fetch-runbooklist-topicssearch-runbooksScored across 3 tools
Each tool has a distinct purpose: fetching a runbook by topic, listing all topics, and searching by keyword. There is no overlap in functionality, making it easy for an agent to select the correct tool.
All tools follow a consistent verb_noun pattern in snake_case (e.g., fetch-runbook, list-topics). The convention is uniform and predictable.
Three tools is well-scoped for a read-only Kubernetes runbook server. It provides essential operations (list, fetch, search) without unnecessary bloat.
The tool surface covers the core read operations for runbooks: listing topics, fetching by topic, and searching. No obvious gaps exist given the server's stated purpose.
Provides read access to your GKE and Kubernetes resources.
Versioned documentation registry and semantic search for AI tools and coding assistants.
Agentic CI operations for build inspection, failure diagnosis, and runner troubleshooting.
Read and write KukGit repositories, files, issues and pull requests from an AI assistant.