MCP Server for Kubernetes Support Bundles

A Model Context Protocol (MCP) server for AI models to interact with Kubernetes support bundles. This server enables AI models to analyze and troubleshoot Kubernetes clusters by exploring support bundles generated by the Troubleshoot tool.

Features

🚀 Bundle Management: Initialize and manage Kubernetes support bundles
🎮 Command Execution: Run kubectl commands against bundle's API server
📁 File Explorer: Navigate and search files within the bundle
🔐 Secure Authentication: Token-based authentication for bundle access
🐳 Container Support: Run as a containerized application
⚡ Single Bundle Mode: Stateless operation for ephemeral/serverless deployments

Single Bundle Mode (Stateless Operation)

For stateless/ephemeral deployments (Temporal workflows, serverless functions, container-per-request architectures), enable Single Bundle Mode:

export MCP_SINGLE_BUNDLE_MODE=true
export PRESERVE_BUNDLES=true
export MCP_BUNDLE_STORAGE=/persistent-storage/bundles

What is Single Bundle Mode?

Single Bundle Mode eliminates in-memory bundle state tracking by treating the presence of a bundle on disk as the source of truth. This enables:

Automatic Bundle Restoration: When the server starts, it auto-activates the bundle persisted on disk
Stateless Server Restarts: Each server restart automatically uses the persisted bundle without re-initialization
Single Bundle Invariant: Only one bundle can exist at a time, preventing state confusion
Seamless Temporal/Serverless Integration: Works perfectly with short-lived server instances

Usage Pattern

# Activity 1: Initialize bundle
# Server starts → downloads bundle → exits
initialize_bundle(url="https://example.com/bundle.tar.gz")

# Activity 2: Use bundle (new server instance)
# Server starts → auto-activates bundle from disk → succeeds
list_files(path="/kubernetes/pods")

# Activity 3: Run kubectl (another new server instance)
# Server starts → auto-activates bundle → succeeds
kubectl(command="get pods")

When to Use Single Bundle Mode

✅ Use when:

Running in Temporal workflows where each activity spawns a new server
Deploying to serverless/lambda environments with short-lived functions
Using container-per-request architectures
Server instances are frequently restarted

❌ Don't use when:

You need to work with multiple bundles simultaneously
Running long-lived server instances (default mode works fine)
Bundle state can be maintained in memory

Configuration Details

Environment Variable	Default	Description
`MCP_SINGLE_BUNDLE_MODE`	`false`	Enable single bundle mode
`PRESERVE_BUNDLES`	`false`	Keep bundle files on disk after cleanup
`MCP_BUNDLE_STORAGE`	temp dir	Directory for persistent bundle storage

Note: PRESERVE_BUNDLES=true must be set with single bundle mode to ensure bundles persist across server restarts.

Quick Start

Using Podman

The easiest way to get started is using Podman:

# Build the image (uses melange/apko instead of Containerfile)
./scripts/build.sh

# Run the server
podman run -i --rm \
  -v "/path/to/bundles:/data/bundles" \
  -e SBCTL_TOKEN="your-token" \
  troubleshoot-mcp-server-dev:latest

See the Podman documentation for comprehensive container configuration details.

Manual Installation

Ensure you have Python 3.13 installed
Set up environment with UV (recommended):

# Automatically creates and sets up environment with best available Python
./scripts/setup_env.sh

# OR create manually with UV
uv venv -p python3.13 .venv
uv pip install -e ".[dev]"  # For development with testing tools

Set up your authentication token:

export SBCTL_TOKEN=your-token

Run the server using UV:

uv run python -m troubleshoot_mcp_server

Container Image Variants

This project provides two distinct container image variants:

Development Image: `troubleshoot-mcp-server-dev:latest`

Purpose: Local development and testing
Built by: ./scripts/build.sh (default)
Usage: When building from source or developing locally

Example:

./scripts/build.sh
podman run -i --rm troubleshoot-mcp-server-dev:latest

Production Image: `troubleshoot-mcp-server:latest`

Purpose: Official releases and production deployments
Built by: CI/CD pipeline with IMAGE_NAME=troubleshoot-mcp-server ./scripts/build.sh
Usage: In production environments or when using official releases

Example:

IMAGE_NAME=troubleshoot-mcp-server ./scripts/build.sh
podman run -i --rm troubleshoot-mcp-server:latest

Why Two Variants?

The -dev suffix prevents conflicts between local development images and official production releases. This allows users to:

Use official container releases without interference from local builds
Develop and test locally without overwriting production images
Maintain clear separation between development and production environments

Documentation

For comprehensive documentation, see:

User Guide: Installation, configuration, and usage instructions
API Reference: Detailed API documentation
Developer Guide: Information for developers
Podman Guide: Container setup and configuration
System Architecture: Overall system design
Troubleshooting Guide: Solutions for common issues
Release Process: How to create new releases

The examples directory contains reference configurations for developers. These files should not be modified.

Tools

The MCP server provides the following tools for AI models:

Bundle Management

initialize_bundle: Initialize a support bundle for use

Kubectl Commands

kubectl: Execute kubectl commands against the bundle

File Operations

list_files: List files and directories
read_file: Read file contents
grep_files: Search for patterns in files

Example Usage

AI models can interact with the server using the MCP protocol:

// Request to list files
{
  "name": "list_files",
  "input": {
    "path": "/kubernetes/pods",
    "recursive": false
  }
}

// Response (simplified)
{
  "content": "Listed files in /kubernetes/pods non-recursively:\n```json\n[\n  {\n    \"name\": \"kube-system\",\n    \"path\": \"/kubernetes/pods/kube-system\",\n    \"type\": \"directory\",\n    \"size\": null,\n    \"modified\": \"2025-04-10T12:30:45Z\"\n  },\n  {\n    \"name\": \"pod-definition.yaml\",\n    \"path\": \"/kubernetes/pods/pod-definition.yaml\",\n    \"type\": \"file\",\n    \"size\": 1254,\n    \"modified\": \"2025-04-10T12:30:45Z\"\n  }\n]\n```\nDirectory metadata:\n```json\n{\n  \"path\": \"/kubernetes/pods\",\n  \"recursive\": false,\n  \"total_files\": 1,\n  \"total_dirs\": 1\n}\n```"
}

Project Structure

├── docs/                      # Documentation
│   ├── CLAUDE.md              # AI assistant instructions
│   ├── PODMAN.md              # Podman configuration guide
│   ├── README.md              # Project overview (this file)
│   ├── docs/                  # Detailed documentation
│   │   ├── agentic/           # AI agent documentation
│   │   ├── components/        # Component design docs
│   │   └── examples/          # Example prompts and usage
│   └── tasks/                 # Development tasks
│       ├── completed/         # Completed tasks
│       ├── started/           # Tasks in progress
│       └── ready/             # Tasks ready to implement
├── examples/                  # Example configurations (for reference only)
│   └── mcp-servers/           # MCP server example configs
├── scripts/                   # Utility scripts
│   ├── build.sh               # Podman build script
│   └── run.sh                 # Podman run script
├── src/                       # Source code
│   └── troubleshoot_mcp_server/
│       ├── __init__.py
│       ├── __main__.py        # Entry point
│       ├── bundle.py          # Bundle management
│       ├── cli.py             # CLI interface
│       ├── config.py          # Configuration management
│       ├── files.py           # File operations
│       ├── kubectl.py         # Kubectl command execution
│       ├── lifecycle.py       # Bundle lifecycle management
│       └── server.py          # MCP server implementation
└── tests/                     # Test files
    ├── e2e/                   # End-to-end tests
    ├── fixtures/              # Test fixtures
    ├── functional/            # Functional tests (MCP protocol validation)
    ├── integration/           # Integration tests
    ├── unit/                  # Unit tests
    └── util/                  # Test utilities

Development

Installation

For development, install the package in editable mode with development dependencies:

# Clone the repository
git clone https://github.com/your-username/troubleshoot-mcp-server.git
cd troubleshoot-mcp-server

# Set up the development environment using UV
./scripts/setup_env.sh

# Or manually with UV
uv venv -p python3.13 .venv
uv pip install -e ".[dev]"

For detailed guidance on dependency management, see our Dependency Management Guide.

Code Style

Code formatting is done using Ruff:

# Format code with Ruff
uv run ruff format .

# Lint code with Ruff
uv run ruff check .

Testing

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run a specific test type using markers
uv run pytest -m unit
uv run pytest -m integration
uv run pytest -m functional  # MCP protocol validation
uv run pytest -m e2e

# Run tests with detailed warnings
uv run pytest -W all

# Run tests with warnings as errors
uv run pytest -W error

# Or use the helper script
./scripts/run_tests.sh unit
./scripts/run_tests.sh integration

Requirements

Python 3.13
kubectl command-line tool
sbctl command-line tool for bundle management
Token for authentication (set as SBCTL_TOKEN or REPLICATED environment variable)

All dependencies are included in the Podman container, making it the recommended deployment method.

Contributing

Contributions are welcome! Please see the Developer Guide for details on how to contribute.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 148 Commits
.claude		.claude
.github		.github
docs		docs
scripts		scripts
src/troubleshoot_mcp_server		src/troubleshoot_mcp_server
tasks		tasks
tests		tests
.containerignore		.containerignore
.gitignore		.gitignore
.melange.yaml		.melange.yaml
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
PODMAN.md		PODMAN.md
README.md		README.md
RELEASE.md		RELEASE.md
apko.yaml		apko.yaml
conftest.py		conftest.py
melange.rsa.pub		melange.rsa.pub
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
simple_mcp_test.py		simple_mcp_test.py
test_mock_audit_results.md		test_mock_audit_results.md
uv.lock		uv.lock

License

chris-sanders/troubleshoot-mcp-server

Folders and files

Latest commit

History

Repository files navigation

MCP Server for Kubernetes Support Bundles

Features

Single Bundle Mode (Stateless Operation)

What is Single Bundle Mode?

Usage Pattern

When to Use Single Bundle Mode

Configuration Details

Quick Start

Using Podman

Manual Installation

Container Image Variants

Development Image: troubleshoot-mcp-server-dev:latest

Production Image: troubleshoot-mcp-server:latest

Why Two Variants?

Documentation

Tools

Bundle Management

Kubectl Commands

File Operations

Example Usage

Project Structure

Development

Installation

Code Style

Testing

Requirements

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors 2

Uh oh!

Languages

Development Image: `troubleshoot-mcp-server-dev:latest`

Production Image: `troubleshoot-mcp-server:latest`

Packages