# MCP Server for Kubernetes Support Bundles
[](LICENSE)
[](https://www.python.org/downloads/)
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](https://troubleshoot.sh/) 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:
```bash
# 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](PODMAN.md) for comprehensive container configuration details.
### Manual Installation
1. Ensure you have Python 3.13 installed
2. Set up environment with UV (recommended):
```bash
# 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:
```bash
export SBCTL_TOKEN=your-token
```
4. Run the server using UV:
```bash
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**:
```bash
./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**:
```bash
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](docs/user_guide.md): Installation, configuration, and usage instructions
- [API Reference](docs/api_reference.md): Detailed API documentation
- [Developer Guide](docs/developer_guide.md): Information for developers
- [Podman Guide](PODMAN.md): Container setup and configuration
- [System Architecture](docs/architecture.md): Overall system design
- [Troubleshooting Guide](docs/troubleshooting.md): Solutions for common issues
- [Release Process](RELEASE.md): How to create new releases
The [examples](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:
```json
// 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
├── integration/ # Integration tests
├── unit/ # Unit tests
└── util/ # Test utilities
```
## Development
### Installation
For development, install the package in editable mode with development dependencies:
```bash
# 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](docs/development/dependency_management.md).
### Code Style
Code formatting is done using Ruff:
```bash
# Format code with Ruff
uv run ruff format .
# Lint code with Ruff
uv run ruff check .
```
### Testing
```bash
# 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](docs/developer_guide.md) for details on how to contribute.
## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "troubleshoot-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "mcp, kubernetes, troubleshoot, support-bundle, ai, claude, debugging",
"author": null,
"author_email": "Chris Nesbitt-Smith <chris@cns.me>",
"download_url": "https://files.pythonhosted.org/packages/a2/df/416fb6cba598b8b6be3de368b9913231973cee1328d6006e8f7ffc4ba434/troubleshoot_mcp_server-1.12.0.tar.gz",
"platform": null,
"description": "# MCP Server for Kubernetes Support Bundles\n\n[](LICENSE)\n[](https://www.python.org/downloads/)\n\nA 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](https://troubleshoot.sh/) tool.\n\n## Features\n\n- \ud83d\ude80 **Bundle Management**: Initialize and manage Kubernetes support bundles\n- \ud83c\udfae **Command Execution**: Run kubectl commands against bundle's API server\n- \ud83d\udcc1 **File Explorer**: Navigate and search files within the bundle\n- \ud83d\udd10 **Secure Authentication**: Token-based authentication for bundle access\n- \ud83d\udc33 **Container Support**: Run as a containerized application\n\n## Quick Start\n\n### Using Podman\n\nThe easiest way to get started is using Podman:\n\n```bash\n# Build the image (uses melange/apko instead of Containerfile)\n./scripts/build.sh\n\n# Run the server\npodman run -i --rm \\\n -v \"/path/to/bundles:/data/bundles\" \\\n -e SBCTL_TOKEN=\"your-token\" \\\n troubleshoot-mcp-server-dev:latest\n```\n\nSee the [Podman documentation](PODMAN.md) for comprehensive container configuration details.\n\n### Manual Installation\n\n1. Ensure you have Python 3.13 installed\n2. Set up environment with UV (recommended):\n\n```bash\n# Automatically creates and sets up environment with best available Python\n./scripts/setup_env.sh\n\n# OR create manually with UV\nuv venv -p python3.13 .venv\nuv pip install -e \".[dev]\" # For development with testing tools\n```\n\n3. Set up your authentication token:\n\n```bash\nexport SBCTL_TOKEN=your-token\n```\n\n4. Run the server using UV:\n\n```bash\nuv run python -m troubleshoot_mcp_server\n```\n\n## Container Image Variants\n\nThis project provides two distinct container image variants:\n\n### Development Image: `troubleshoot-mcp-server-dev:latest`\n- **Purpose**: Local development and testing\n- **Built by**: `./scripts/build.sh` (default)\n- **Usage**: When building from source or developing locally\n- **Example**: \n ```bash\n ./scripts/build.sh\n podman run -i --rm troubleshoot-mcp-server-dev:latest\n ```\n\n### Production Image: `troubleshoot-mcp-server:latest`\n- **Purpose**: Official releases and production deployments\n- **Built by**: CI/CD pipeline with `IMAGE_NAME=troubleshoot-mcp-server ./scripts/build.sh`\n- **Usage**: In production environments or when using official releases\n- **Example**:\n ```bash\n IMAGE_NAME=troubleshoot-mcp-server ./scripts/build.sh\n podman run -i --rm troubleshoot-mcp-server:latest\n ```\n\n### Why Two Variants?\n\nThe `-dev` suffix prevents conflicts between local development images and official production releases. This allows users to:\n- Use official container releases without interference from local builds\n- Develop and test locally without overwriting production images\n- Maintain clear separation between development and production environments\n\n## Documentation\n\nFor comprehensive documentation, see:\n\n- [User Guide](docs/user_guide.md): Installation, configuration, and usage instructions\n- [API Reference](docs/api_reference.md): Detailed API documentation\n- [Developer Guide](docs/developer_guide.md): Information for developers\n- [Podman Guide](PODMAN.md): Container setup and configuration\n- [System Architecture](docs/architecture.md): Overall system design\n- [Troubleshooting Guide](docs/troubleshooting.md): Solutions for common issues\n- [Release Process](RELEASE.md): How to create new releases\n\nThe [examples](examples/) directory contains reference configurations for developers. These files should not be modified.\n\n## Tools\n\nThe MCP server provides the following tools for AI models:\n\n### Bundle Management\n\n- `initialize_bundle`: Initialize a support bundle for use\n\n### Kubectl Commands\n\n- `kubectl`: Execute kubectl commands against the bundle\n\n### File Operations\n\n- `list_files`: List files and directories\n- `read_file`: Read file contents\n- `grep_files`: Search for patterns in files\n\n## Example Usage\n\nAI models can interact with the server using the MCP protocol:\n\n```json\n// Request to list files\n{\n \"name\": \"list_files\",\n \"input\": {\n \"path\": \"/kubernetes/pods\",\n \"recursive\": false\n }\n}\n\n// Response (simplified)\n{\n \"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```\"\n}\n```\n\n## Project Structure\n\n```\n\u251c\u2500\u2500 docs/ # Documentation\n\u2502 \u251c\u2500\u2500 CLAUDE.md # AI assistant instructions\n\u2502 \u251c\u2500\u2500 PODMAN.md # Podman configuration guide\n\u2502 \u251c\u2500\u2500 README.md # Project overview (this file)\n\u2502 \u251c\u2500\u2500 docs/ # Detailed documentation\n\u2502 \u2502 \u251c\u2500\u2500 agentic/ # AI agent documentation\n\u2502 \u2502 \u251c\u2500\u2500 components/ # Component design docs\n\u2502 \u2502 \u2514\u2500\u2500 examples/ # Example prompts and usage\n\u2502 \u2514\u2500\u2500 tasks/ # Development tasks\n\u2502 \u251c\u2500\u2500 completed/ # Completed tasks\n\u2502 \u251c\u2500\u2500 started/ # Tasks in progress\n\u2502 \u2514\u2500\u2500 ready/ # Tasks ready to implement\n\u251c\u2500\u2500 examples/ # Example configurations (for reference only)\n\u2502 \u2514\u2500\u2500 mcp-servers/ # MCP server example configs\n\u251c\u2500\u2500 scripts/ # Utility scripts\n\u2502 \u251c\u2500\u2500 build.sh # Podman build script\n\u2502 \u2514\u2500\u2500 run.sh # Podman run script\n\u251c\u2500\u2500 src/ # Source code\n\u2502 \u2514\u2500\u2500 troubleshoot_mcp_server/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 __main__.py # Entry point\n\u2502 \u251c\u2500\u2500 bundle.py # Bundle management\n\u2502 \u251c\u2500\u2500 cli.py # CLI interface\n\u2502 \u251c\u2500\u2500 config.py # Configuration management\n\u2502 \u251c\u2500\u2500 files.py # File operations\n\u2502 \u251c\u2500\u2500 kubectl.py # Kubectl command execution\n\u2502 \u251c\u2500\u2500 lifecycle.py # Bundle lifecycle management\n\u2502 \u2514\u2500\u2500 server.py # MCP server implementation\n\u2514\u2500\u2500 tests/ # Test files\n \u251c\u2500\u2500 e2e/ # End-to-end tests\n \u251c\u2500\u2500 fixtures/ # Test fixtures \n \u251c\u2500\u2500 integration/ # Integration tests\n \u251c\u2500\u2500 unit/ # Unit tests\n \u2514\u2500\u2500 util/ # Test utilities\n```\n\n## Development\n\n### Installation\n\nFor development, install the package in editable mode with development dependencies:\n\n```bash\n# Clone the repository\ngit clone https://github.com/your-username/troubleshoot-mcp-server.git\ncd troubleshoot-mcp-server\n\n# Set up the development environment using UV\n./scripts/setup_env.sh\n\n# Or manually with UV\nuv venv -p python3.13 .venv\nuv pip install -e \".[dev]\"\n```\n\nFor detailed guidance on dependency management, see our [Dependency Management Guide](docs/development/dependency_management.md).\n\n### Code Style\n\nCode formatting is done using Ruff:\n\n```bash\n# Format code with Ruff\nuv run ruff format .\n\n# Lint code with Ruff\nuv run ruff check .\n```\n\n### Testing\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run with verbose output\nuv run pytest -v\n\n# Run a specific test type using markers\nuv run pytest -m unit\nuv run pytest -m integration\nuv run pytest -m e2e\n\n# Run tests with detailed warnings\nuv run pytest -W all\n\n# Run tests with warnings as errors\nuv run pytest -W error\n\n# Or use the helper script\n./scripts/run_tests.sh unit\n./scripts/run_tests.sh integration\n```\n\n## Requirements\n\n- Python 3.13\n- `kubectl` command-line tool\n- `sbctl` command-line tool for bundle management\n- Token for authentication (set as `SBCTL_TOKEN` or `REPLICATED` environment variable)\n\nAll dependencies are included in the Podman container, making it the recommended deployment method.\n\n## Contributing\n\nContributions are welcome! Please see the [Developer Guide](docs/developer_guide.md) for details on how to contribute.\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "MCP server for Kubernetes support bundles",
"version": "1.12.0",
"project_urls": {
"Homepage": "https://github.com/chrisns/troubleshoot-mcp-server",
"Issues": "https://github.com/chrisns/troubleshoot-mcp-server/issues",
"Repository": "https://github.com/chrisns/troubleshoot-mcp-server"
},
"split_keywords": [
"mcp",
" kubernetes",
" troubleshoot",
" support-bundle",
" ai",
" claude",
" debugging"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "75bd544037af87829206a51fb198ab155e70b33fdc2683f4f2d8c7ed5c700767",
"md5": "85db10c4a71d64cc44855a264e42c407",
"sha256": "473e153856a40bf21d2be7cc8baeca1c78c5de2e1e05271323e16cada3b01d89"
},
"downloads": -1,
"filename": "troubleshoot_mcp_server-1.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "85db10c4a71d64cc44855a264e42c407",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 68606,
"upload_time": "2025-08-11T02:07:08",
"upload_time_iso_8601": "2025-08-11T02:07:08.561020Z",
"url": "https://files.pythonhosted.org/packages/75/bd/544037af87829206a51fb198ab155e70b33fdc2683f4f2d8c7ed5c700767/troubleshoot_mcp_server-1.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a2df416fb6cba598b8b6be3de368b9913231973cee1328d6006e8f7ffc4ba434",
"md5": "c751460da7d0d03fbd293033dee87be6",
"sha256": "708d622160eaa7955d810f0c035fdf340e73f5bc5eca552b85b591c75ffe8fa7"
},
"downloads": -1,
"filename": "troubleshoot_mcp_server-1.12.0.tar.gz",
"has_sig": false,
"md5_digest": "c751460da7d0d03fbd293033dee87be6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 66198,
"upload_time": "2025-08-11T02:07:09",
"upload_time_iso_8601": "2025-08-11T02:07:09.775944Z",
"url": "https://files.pythonhosted.org/packages/a2/df/416fb6cba598b8b6be3de368b9913231973cee1328d6006e8f7ffc4ba434/troubleshoot_mcp_server-1.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-11 02:07:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chrisns",
"github_project": "troubleshoot-mcp-server",
"github_not_found": true,
"lcname": "troubleshoot-mcp-server"
}
JSON
