k8s-docs-mcp ☸️

Official Kubernetes Documentation & Canonical YAML Manifest Assistant for Autonomous AI Agents via the Model Context Protocol (MCP).

k8s-docs-mcp connects your AI coding assistant (Cursor, Claude Desktop, Antigravity, VS Code) directly to the upstream source of truth: github.com/kubernetes/website.

💡 The Problem: LLM "Version Blindness" & Hallucinations

General-purpose Large Language Models regularly fail when generating Kubernetes configurations because their training sets mix documentation across outdated releases:

• ❌ Deprecated APIs: Emitting apiVersion: extensions/v1beta1 for Ingress instead of networking.k8s.io/v1.

• ❌ Removed Features: Suggesting PodSecurityPolicy (removed in K8s 1.25) instead of modern PodSecurityStandards or in-tree CEL ValidatingAdmissionPolicy.

• ❌ Formatting Corruption: Mangling YAML indentation, missing mandatory spec fields, or hallucinating non-existent controller flags.

k8s-docs-mcp solves this deterministically:

1. Canonical YAML Manifest Extraction: Extracts exact, verified YAML manifests directly from upstream Kubernetes documentation and examples in < 20 ms, completely bypassing generative LLM mutation.

2. Current Upstream Documentation: Delivers authoritative explanations with exact links to https://kubernetes.io/docs/....

3. Continuous Upstream Synchronization: Pulls weekly updates directly from kubernetes/website (content/en/docs and content/en/examples) using sparse git checkouts to stay aligned with current Kubernetes releases.

Related MCP server: Kube MCP

🏛️ The Cloud Native Agent Trifecta

k8s-docs-mcp works as an independent standalone tool or as the authoritative documentation engine paired with syllabus guides and architectural tutors:

flowchart TD
    IDE["AI Coding Assistant / Agent\n(Claude Desktop, Cursor, Antigravity)"]
    
    IDE -->|"MCP 1: Syllabus & Learning Paths"| S["study-cybercirujas\n(Official CKA/CKS/CNPE Exam Objectives)"]
    IDE -->|"MCP 2: Canonical Docs & Syntax"| K["k8s-docs-mcp\n(Authoritative kubernetes.io Docs & Verified YAMLs)"]
    IDE -->|"MCP 3: In-Depth Architecture"| R["rag-tutor\n(Engineering Books & GraphRAG Platform Patterns)"]
    
    style K fill:#326CE5,stroke:#fff,stroke-width:2px,color:#fff

🛠️ Available MCP Tools

🚀 Quickstart & MCP Configuration

1. Claude Desktop

Add k8s-docs-mcp to your claude_desktop_config.json:

{
  "mcpServers": {
    "k8s-docs": {
      "command": "uvx",
      "args": ["k8s-docs-mcp"]
    }
  }
}

Or for a local development clone:

{
  "mcpServers": {
    "k8s-docs": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/k8s-docs-mcp",
        "run",
        "k8s-docs-mcp"
      ]
    }
  }
}

2. Cursor IDE

In your project root, add to .cursor/mcp.json:

{
  "mcpServers": {
    "k8s-docs": {
      "command": "uvx",
      "args": ["k8s-docs-mcp"]
    }
  }
}

3. Local Development & Testing

# Clone the repository
git clone https://github.com/villadalmine/k8s-docs-mcp.git
cd k8s-docs-mcp

# Install dependencies using uv
uv sync

# Run test suite
uv run pytest tests/

# Execute interactive tool verification
uv run python -c "
from k8s_docs_mcp.server import search_k8s_docs, get_canonical_manifest

print(search_k8s_docs('validating admission policy'))
print('---')
print(get_canonical_manifest('NetworkPolicy'))
"

🔄 Automated Upstream Synchronization

k8s-docs-mcp uses a lightweight sparse checkout mechanism:

# Pulls only Markdown documentation and YAML examples (~25 MB instead of a 2 GB full clone)
uv run python -c "from k8s_docs_mcp.server import sync_upstream_docs; print(sync_upstream_docs())"

The repository includes a scheduled GitHub Action (.github/workflows/sync-upstream.yml) that runs weekly to verify and update indexed Kubernetes documentation against the latest kubernetes/website main branch.

📜 Intellectual Property & Fair Use

• All documentation and manifest examples retrieved from kubernetes/website are licensed by the Kubernetes Authors under Apache License 2.0 and Creative Commons Attribution 4.0 International (CC-BY-4.0).

• k8s-docs-mcp attributes all excerpts directly to their canonical origin on kubernetes.io.

• This project software is open-source under the Apache License 2.0. See LICENSE for details.