What is Troubleshoot Mcp Server

The troubleshoot-mcp-server is a Model Context Protocol (MCP) server designed to facilitate the interaction of AI models with Kubernetes support bundles, enabling analysis and troubleshooting of Kubernetes clusters.

Use cases

Use cases include analyzing support bundles generated by the Troubleshoot tool, executing kubectl commands for cluster management, exploring files within support bundles for diagnostics, and securely managing access to Kubernetes support data.

How to use

To use troubleshoot-mcp-server, you can either run it using Docker by building the image and executing the server with the necessary volume and environment variables, or you can manually install it by setting up a Python virtual environment, installing the package, and running the server with an authentication token.

Key features

Key features include bundle management for Kubernetes support bundles, command execution capabilities against the bundle’s API server, a file explorer for navigating and searching files within the bundle, secure token-based authentication, and support for running as a containerized application.

Where to use

troubleshoot-mcp-server is primarily used in environments where Kubernetes clusters are deployed, particularly in DevOps and IT operations for troubleshooting and analyzing cluster performance and issues.

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

Quick Start

Using Podman

The easiest way to get started is using Podman:

# Build the image
podman build -t mcp-server-troubleshoot:latest -f Containerfile .

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

See the Podman documentation for comprehensive container configuration details.

Manual Installation

1. Ensure you have Python 3.13 installed
2. 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

3. Set up your authentication token:

export SBCTL_TOKEN=your-token

4. Run the server using UV:

uv run python -m mcp_server_troubleshoot

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:

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
│   └── mcp_server_troubleshoot/
│       ├── __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 
    ├── 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/mcp-server-troubleshoot.git
cd mcp-server-troubleshoot

# 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 Black and Ruff:

# Format code with Black
uv run black .

# 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 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.